Intel Mac平台搭建Docusaurus开发环境的完整教程

引言

Docusaurus是Meta(原Facebook)开源的一款静态网站生成器，特别适合构建文档网站、博客和技术文档。本文将详细介绍在Intel芯片的Mac电脑上搭建Docusaurus开发环境的完整步骤，帮助你快速开始使用这个强大的工具。

准备工作

在开始之前，请确保你的Intel Mac满足以下要求：

macOS 10.15 (Catalina)或更高版本
已安装Homebrew（Mac包管理器）
管理员权限（用于安装软件）

第一步：安装Node.js和npm

Docusaurus基于Node.js运行，因此我们需要先安装Node.js环境。

1.1 使用Homebrew安装Node.js

打开终端(Terminal)，执行以下命令：

代码片段

# 更新Homebrew确保获取最新软件包
brew update

# 安装Node.js（这将同时安装npm）
brew install node

1.2 验证安装

安装完成后，检查版本以确保安装成功：

代码片段

node -v
npm -v

正常情况应该显示类似如下的版本号：

代码片段

v16.14.2
8.5.0

注意事项：
– Docusaurus推荐使用Node.js的LTS版本（长期支持版）
– 如果遇到权限问题，可以在命令前加上sudo，但这不是推荐做法

第二步：创建Docusaurus项目

2.1 使用npx创建项目

npx是npm的一个工具，可以运行本地或远程的npm包。执行以下命令创建新项目：

代码片段

npx create-docusaurus@latest my-website classic

参数说明：
– my-website: 你的项目文件夹名称（可自定义）
– classic: Docusaurus的模板类型（也可选择blog等）

2.2 进入项目目录

代码片段

cd my-website

2.3 目录结构说明

创建完成后，你会看到如下目录结构：

代码片段

my-website/
├── blog/                # Markdown格式的博客文章
├── docs/                # Markdown格式的文档
├── src/                 # React组件和CSS样式
├── static/              # 静态文件如图片等
├── docusaurus.config.js # Docusaurus配置文件
└── package.json         # Node.js项目配置文件

第三步：运行开发服务器

3.1 启动开发服务器

代码片段

npm run start

或者使用yarn（如果已安装）：

代码片段

yarn start

3.2 访问本地网站

命令执行后，会自动打开浏览器访问 http://localhost:3000。如果没有自动打开，你可以手动访问这个地址。

开发服务器特点：
– 热重载(Hot Reload): 修改文件后会自动刷新页面
– 错误提示: 会在浏览器和控制台显示错误信息

第四步：常用开发命令介绍

了解以下命令将帮助你更好地开发和构建项目：

命令	描述
`npm run start`	启动开发服务器
`npm run build`	构建生产环境代码
`npm run serve`	本地测试生产环境构建
`npm run clear`	清除缓存和构建文件

第五步：配置IDE（以VS Code为例）

为了获得更好的开发体验，建议配置你的代码编辑器：

插件推荐：
- ESLint – JavaScript代码检查工具
- Prettier – Code formatter – JavaScript代码格式化工具
- MDX – Markdown扩展语法支持
设置推荐：
在项目根目录创建.vscode/settings.json文件：

代码片段

{
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "eslint.validate": ["javascript", "javascriptreact", "typescript", "typescriptreact"],
    "[mdx]": {
        "editor.defaultFormatter": "esbenp.prettier-vscode"
    }
}

FAQ常见问题解决

Q1: npm install时出现权限错误怎么办？

解决方案：

代码片段

# Mac上通常不需要sudo，但如果你必须使用：
sudo chown -R $(whoami) ~/.npm 
sudo chown -R $(whoami) node_modules/

更好的做法是修复npm权限而不使用sudo：

代码片段

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH # Add this to your .zshrc or .bashrc file permanently

Q2: Node.js版本不兼容怎么办？

使用nvm(Node Version Manager)管理多个Node.js版本：

代码片段

# Install nvm (if not already installed)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.1/install.sh | bash

# Install a specific Node version (e.g., v16)
nvm install v16 

# Use the installed version 
nvm use v16 

# Set as default 
nvm alias default v16

Q3: Docusaurus启动时报错”Error: listen EADDRINUSE: address already in use :::3000″

这表示端口3000已被占用。解决方案：

代码片段

# Find the process using port 3000 and kill it:
lsof -i :3000 
kill -9 <PID> 

# Or simply use a different port:
npm run start -- --port=3001

Docusaurus基本配置修改示例

打开docusaurus.config.js文件进行基本配置：

“`javascript title=”docusaurus.config.js”
module.exports = {
title: ‘我的技术博客’, // Website title in browser tab and SEO metadata

代码片段

tagline: '记录学习与成长的点点滴滴', // Subtitle

url: 'https://your-site.com', // Your production website URL

baseUrl: '/', // Base URL for project pages

onBrokenLinks: 'throw', // What to do when a link is broken

favicon: 'img/favicon.ico', // Path to favicon

organizationName: 'your-github-user', // Usually your GitHub org/user name

projectName: 'your-repo-name', // Usually your repo name

themeConfig: {
    navbar: {
        title: '首页',
        logo: {
            alt: 'My Site Logo',
            src: 'img/logo.svg',
        },
        items: [
            {to: 'docs/intro', label: '文档', position: 'left'},
            {to: 'blog', label: '博客', position: 'left'},
            {
                href: 'https://github.com/your-repo',
                label: 'GitHub',
                position: 'right',
            },
        ],
    },
    footer: {
        style: 'dark',
        links: [
            /* Your footer links configuration */
        ],
        copyright: `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`,
    },
},

presets: [
    [
        '@docusaurus/preset-classic',
        {
            docs: {
                sidebarPath: require.resolve('./sidebars.js'),
                editUrl:
                    'https://github.com/your-repo/edit/main/website/',
            },
            blog: {
                showReadingTime: true,
                editUrl:
                    'https://github.com/your-repo/edit/main/website/blog/',
            },
            theme: {
                customCss: require.resolve('./src/css/custom.css'),
            },
        },  
    ],
],

};

代码片段


## Markdown文档编写示例

在`docs/intro.md`中添加你的第一篇文档：

```markdown title="docs/intro.md"
---
id： intro 
title： Getting Started 
---

欢迎来到我的技术文档！

这是你的第一篇文章。你可以在这里编写Markdown内容。

## Section标题 

Here's a code block:

```jsx 
function HelloCode() { 
    return <div>Hello world!</div>; 
}

Learn more about Markdown syntax。

代码片段


## Docker开发环境（可选）

如果你想使用Docker进行开发和部署：

1. **创建Dockerfile**

```dockerfile title="Dockerfile"
FROM node：16 

WORKDIR /app 

COPY package*.json ./ 

RUN npm install 

COPY . . 

EXPOSE $PORT 

CMD ["npm"，"run"，"start"]

构建和运行

代码片段

docker build -t docusaurus-site . 

docker run -p $PORT:$PORT docusaurus-site

Git版本控制集成（最佳实践）

建议将你的Docusaurus项目纳入Git版本控制:

初始化Git仓库

代码片段

git init && git add . && git commit -m "Initial commit"

创建.gitignore文件

代码片段

node_modules/
build/
.DS_Store  
.env      
.temp     
.cache    
dist      
.yarn     
.vscode   
*.log     
*.swp     
*.swo     
*.tmp     
*.bak     
*.orig    
*~

3.连接到远程仓库(GitHub/GitLab)

代码片段

git remote add origin https://github.com/YOUR_USERNAME/YOUR_REPO.git 

git push -u origin main

4.自动化部署(可选)

你可以设置GitHub Actions自动部署到GitHub Pages:

““yaml title=”.github/workflows/deploy.yml”
name： Deploy to GitHub Pages

on：
push：
branches：[main]

jobs：
deploy：
runs-on： ubuntu-latest

steps：
– uses： actions/checkout@v2

uses： actions/setup-node@v2
with：
node-version：‘16’
name： Install dependencies
run： npm install
name： Build website
run： npm run build
name： Deploy to GH Pages
uses： peaceiris/actions-gh-pages@v3
with：
githubtoken:${{ secrets.GITHUBTOKEN }}
publish_dir:/build/my-website

““

通过以上步骤,你已经成功在Intel Mac上搭建了完整的Docusaurus开发环境,可以开始构建你的文档网站了!如果在过程中遇到任何问题,可以参考官方文档或社区讨论区寻求帮助.

Happy documenting! 🚀