docusaurus.config.js配置

我来详细讲解 docusaurus.config.js 的完整配置。我创建了一个超详细的 docusaurus.config.js 配置指南！

配置文件结构

module.exports = {
  // 1. 站点元数据
  title: '网站标题',
  url: 'https://your-domain.com',
  baseUrl: '/',
  
  // 2. 部署配置
  organizationName: 'github-username',
  projectName: 'repo-name',
  
  // 3. 国际化
  i18n: {...},
  
  // 4. 预设配置（包含文档、博客、主题）
  presets: [...],
  
  // 5. 主题配置
  themeConfig: {...},
  
  // 6. 插件
  plugins: [...],
};

核心配置项详解

1️⃣ 站点基础配置 (必填)

{
  title: 'IT知识学习网站',           // 网站标题
  tagline: '全面的编程教程',         // 副标题
  favicon: 'img/favicon.ico',       // 图标
  url: 'https://example.com',       // 生产环境 URL
  baseUrl: '/',                     // 基础路径
}

2️⃣ GitHub Pages 部署配置

{
  organizationName: 'your-username', // GitHub 用户名
  projectName: 'your-repo',         // 仓库名
  deploymentBranch: 'gh-pages',     // 部署分支
  
  // 如果部署到 https://username.github.io/repo-name/
  url: 'https://username.github.io',
  baseUrl: '/repo-name/',
}

3️⃣ 国际化配置

i18n: {
  defaultLocale: 'zh-CN',
  locales: ['zh-CN', 'en'],
  localeConfigs: {
    'zh-CN': {
      label: '简体中文',
    },
    en: {
      label: 'English',
    },
  },
}

4️⃣ 文档配置 (presets.docs)

presets: [
  [
    'classic',
    {
      docs: {
        sidebarPath: require.resolve('./sidebars.js'),
        editUrl: 'https://github.com/xxx/edit/main/',
        showLastUpdateTime: true,      // 显示更新时间
        showLastUpdateAuthor: true,     // 显示作者
        routeBasePath: 'docs',          // 文档路由
        path: 'docs',                   // 文档目录
      },
    },
  ],
]

5️⃣ 博客配置 (presets.blog)

blog: {
  showReadingTime: true,        // 阅读时间
  postsPerPage: 10,            // 每页文章数
  blogTitle: '博客',
  blogSidebarTitle: '最近文章',
  blogSidebarCount: 5,
  
  feedOptions: {               // RSS 订阅
    type: 'all',
    copyright: '© 2024',
  },
}

6️⃣ 主题配置 (themeConfig)

themeConfig: {
  navbar: {...},      // 导航栏
  footer: {...},      // 页脚
  prism: {...},       // 代码高亮
  algolia: {...},     // 搜索
  colorMode: {...},   // 颜色模式
}

常用配置场景

场景 1：最简单配置（快速开始）

module.exports = {
  title: '我的网站',
  url: 'https://example.com',
  baseUrl: '/',
  
  presets: [
    [
      'classic',
      {
        docs: {
          sidebarPath: require.resolve('./sidebars.js'),
        },
        blog: false,
      },
    ],
  ],
  
  themeConfig: {
    navbar: {
      title: '我的网站',
      items: [
        {type: 'docSidebar', sidebarId: 'tutorialSidebar', label: '文档'},
      ],
    },
  },
};

场景 2：部署到 GitHub Pages

module.exports = {
  url: 'https://yourusername.github.io',
  baseUrl: '/your-repo/',
  organizationName: 'yourusername',
  projectName: 'your-repo',
  
  // 其他配置...
};

场景 3：多语言网站

module.exports = {
  i18n: {
    defaultLocale: 'zh-CN',
    locales: ['zh-CN', 'en', 'ja'],
  },
  
  themeConfig: {
    navbar: {
      items: [
        {type: 'localeDropdown', position: 'right'},
      ],
    },
  },
};

场景 4：添加 Google Analytics

presets: [
  [
    'classic',
    {
      gtag: {
        trackingID: 'G-XXXXXXXXXX',
        anonymizeIP: true,
      },
    },
  ],
]

场景 5：自定义域名

{
  url: 'https://www.yourdomain.com',
  baseUrl: '/',
  
  // 在 static/ 目录添加 CNAME 文件
  // 内容为: www.yourdomain.com
}

配置验证

检查配置是否正确

# 启动开发服务器（会验证配置）
npm start

# 构建（会显示详细错误）
npm run build

常见错误

错误	原因	解决方法
url is required	缺少 url 字段	添加 url: 'https://...'
baseUrl should start and end with /	baseUrl 格式错误	改为 baseUrl: '/xxx/'
Cannot find module sidebars.js	侧边栏文件不存在	创建 sidebars.js

配置优先级

命令行参数 > 环境变量 > docusaurus.config.js > 默认值

例如：

# 覆盖 baseUrl
npm start -- --baseUrl /test/

推荐的配置顺序

1. ✅ 先配置基础信息：title, url, baseUrl
2. ✅ 配置部署：organizationName, projectName
3. ✅ 配置文档：docs 路径和侧边栏
4. ✅ 配置导航和页脚：navbar, footer
5. ✅ 配置代码高亮：prism
6. ✅ 可选功能：搜索、国际化、分析等

需要某个特定功能的详细配置说明吗？比如如何配置版本管理、如何配置 PWA 等？