搬瓦工搭建 Docusaurus 文档网站教程

Docusaurus 是 Meta（Facebook）开源的文档网站生成器，基于 React 构建，专为技术文档设计。它支持文档版本管理、国际化、博客功能和全文搜索，被众多知名开源项目采用。本文将介绍如何在搬瓦工 VPS 上搭建 Docusaurus 文档站并通过 Nginx 部署。购买搬瓦工 VPS 请参考全部方案，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。

一、安装 Node.js

apt update && apt upgrade -y
curl -fsSL https://deb.nodesource.com/setup_20.x | bash -
apt install -y nodejs git
node -v && npm -v

二、创建 Docusaurus 项目

cd /opt
npx create-docusaurus@latest mydocs classic --typescript
cd mydocs

2.1 配置站点

编辑 docusaurus.config.ts 文件，设置站点基本信息：

cat > /opt/mydocs/docusaurus.config.ts << 'EOF'
import {themes as prismThemes} from 'prism-react-renderer';
import type {Config} from '@docusaurus/types';

const config: Config = {
  title: '项目文档',
  tagline: '简洁高效的技术文档',
  favicon: 'img/favicon.ico',
  url: 'https://docs.yourdomain.com',
  baseUrl: '/',
  organizationName: 'your-org',
  projectName: 'your-project',
  onBrokenLinks: 'throw',
  onBrokenMarkdownLinks: 'warn',
  i18n: {
    defaultLocale: 'zh-Hans',
    locales: ['zh-Hans'],
  },
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: './sidebars.ts',
          routeBasePath: '/',
        },
        blog: {
          showReadingTime: true,
        },
        theme: {
          customCss: './src/css/custom.css',
        },
      },
    ],
  ],
  themeConfig: {
    navbar: {
      title: '项目文档',
      items: [
        {type: 'docSidebar', sidebarId: 'tutorialSidebar', position: 'left', label: '文档'},
        {to: '/blog', label: '博客', position: 'left'},
        {href: 'https://github.com/your-org/your-project', label: 'GitHub', position: 'right'},
      ],
    },
    prism: {
      theme: prismThemes.github,
      darkTheme: prismThemes.dracula,
    },
  },
};

export default config;
EOF

三、编写文档

文档文件存放在 docs/ 目录中，使用 Markdown 或 MDX 格式编写。Docusaurus 支持 React 组件嵌入到 Markdown 中。

# 文档目录结构示例
# docs/
#   intro.md
#   getting-started/
#     installation.md
#     configuration.md
#   guides/
#     basic-usage.md

四、本地预览

cd /opt/mydocs
npm start -- --host 0.0.0.0

五、构建与部署

5.1 构建静态文件

npm run build

构建产物在 build/ 目录中。

5.2 Nginx 部署

apt install nginx -y

cat > /etc/nginx/sites-available/docusaurus.conf << 'EOF'
server {
    listen 80;
    server_name docs.yourdomain.com;
    root /opt/mydocs/build;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location ~* \.(css|js|png|jpg|jpeg|gif|ico|svg|woff|woff2)$ {
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    gzip on;
    gzip_types text/plain text/css application/json application/javascript text/xml;
}
EOF

ln -sf /etc/nginx/sites-available/docusaurus.conf /etc/nginx/sites-enabled/
rm -f /etc/nginx/sites-enabled/default
nginx -t && systemctl restart nginx

六、文档版本管理

# 创建版本快照
npm run docusaurus docs:version 1.0

# 版本存储在 versioned_docs/ 和 versioned_sidebars/ 中

七、自动化部署

cat > /opt/mydocs/deploy.sh << 'EOF'
#!/bin/bash
cd /opt/mydocs
git pull origin main
npm install
npm run build
echo "[$(date)] Docusaurus deployed"
EOF
chmod +x /opt/mydocs/deploy.sh

八、SSL 证书

apt install certbot python3-certbot-nginx -y
certbot --nginx -d docs.yourdomain.com

九、常见问题

构建内存不足

Docusaurus 构建可能需要较多内存。如果遇到 OOM 错误，可以增加 Node.js 内存限制：

export NODE_OPTIONS="--max-old-space-size=4096"
npm run build

路由 404 错误

Docusaurus 使用客户端路由，Nginx 需要配置所有路由都回退到 index.html，即 try_files $uri $uri/ /index.html。

总结

Docusaurus 是构建技术文档网站的专业工具，功能丰富、生态完善。在搬瓦工 VPS 上部署可以获得完整的控制权。其他文档站工具还有 MkDocs、VitePress 等。购买搬瓦工 VPS 请访问 bwh81.net，使用优惠码 NODESEEK2026 可享受 6.77% 的折扣。