如何使用Docker作为本地开发环境开发Docusaurus文档？

嘿，我刚好折腾过用Docker做Docusaurus本地开发，完全不用在本地装Node环境，给你一步步说清楚怎么做！

前提准备 #

首先确保你本地已经安装了 Docker 和 Docker Compose，这俩是基础，没装的话先搞定它们。

情况1：从零新建Docusaurus项目 #

如果还没创建项目，直接用Docker容器完成初始化，不用碰本地Node：

1. 先创建一个空的项目目录并进入：

   mkdir my-docusaurus-site && cd my-docusaurus-site
   

2. 运行Docker命令初始化项目：

   docker run --rm -v $(pwd):/app node:18-alpine sh -c "npx create-docusaurus@latest . classic --typescript --no-git"
   

   解释下参数：
   • --rm：容器跑完自动删除，不占空间
   • -v $(pwd):/app：把本地当前目录挂载到容器里的/app，初始化的文件会直接写到本地
   • node:18-alpine：用轻量的Node 18 Alpine镜像（Docusaurus推荐Node 18+版本）
   • 后面的命令就是Docusaurus官方的初始化命令，选classic模板，加--typescript可选TypeScript支持，--no-git可以跳过初始化Git（不需要的话删掉就行）

情况2：已有Docusaurus项目 #

如果已经有现成的项目，直接跳到下一步配置Docker环境就行。

配置Docker环境（核心步骤） #

在项目根目录创建两个文件：Dockerfile 和 docker-compose.yml，以后启动开发环境只用一条命令。

1. 编写Dockerfile #

创建Dockerfile并写入以下内容：

# 基于官方Node 18 Alpine镜像构建
FROM node:18-alpine

# 设置容器内的工作目录
WORKDIR /app

# 先复制依赖配置文件，利用Docker缓存加快构建速度
COPY package*.json ./

# 安装项目依赖，加--no-funding和--no-audit跳过不必要的检查，加快安装
RUN npm ci --no-funding --no-audit

# 复制项目所有代码文件到容器内
COPY . .

# 暴露Docusaurus默认的开发端口3000
EXPOSE 3000

# 启动开发服务器，--host 0.0.0.0是为了让Docker外部能访问容器内的服务
CMD ["npm", "run", "start", "--", "--host", "0.0.0.0"]

2. 编写docker-compose.yml #

创建docker-compose.yml并写入以下内容：

version: '3.8'

services:
  docusaurus:
    build: .
    ports:
      - "3000:3000"  # 本地端口:容器端口，冲突的话改左边的数字
    volumes:
      # 挂载核心内容目录/文件，实现本地修改实时同步到容器（热重载）
      - ./docs:/app/docs
      - ./src:/app/src
      - ./static:/app/static
      - ./docusaurus.config.js:/app/docusaurus.config.js
      - ./sidebars.js:/app/sidebars.js
      # 如果用TypeScript，加上这行
      - ./tsconfig.json:/app/tsconfig.json
    environment:
      - NODE_ENV=development

这里挂载的都是你日常会修改的文件/目录，改本地的内容后，容器里的开发服务器会自动热重载，不用重启容器。

启动开发服务器 #

一切配置好后，在项目根目录运行：

docker-compose up --build

• 第一次运行会构建Docker镜像，之后再启动可以去掉--build，直接docker-compose up就行
• 等控制台提示Docusaurus server started on http://localhost:3000/，打开浏览器访问这个地址就能看到你的文档站点了！

实用小技巧 #

1. 端口冲突解决：如果本地3000端口被占用，修改docker-compose.yml里的ports配置，比如改成3001:3000，然后访问http://localhost:3001
2. 更新依赖：如果修改了package.json，需要重新构建镜像才能安装新依赖，运行docker-compose up --build即可
3. 生成生产静态文件：要打包生产版本的话，运行：

   docker-compose run --rm docusaurus npm run build
   

   生成的静态文件会在本地的build目录里（如果没挂载build目录，也可以用docker cp命令从容器里复制出来：docker cp <容器ID>:/app/build ./）
4. 热重载延迟问题：在Windows WSL2或macOS上，可能出现文件修改后热重载延迟的情况，可以试试在docusaurus.config.js里添加监听插件：

   module.exports = {
     // ...其他配置
     plugins: [
       require('docusaurus-plugin-watch-external')({
         paths: ['./docs', './src']
       })
     ]
   }
   

   记得先在容器里安装这个插件：docker-compose run --rm docusaurus npm install docusaurus-plugin-watch-external --save-dev

备注：内容来源于stack exchange，提问作者Markus