第3章 Docusaurus 2.x CLI 指南：核心命令与配置详解

版本：2.x CLI Docusaurus 提供了一组脚本，用于生成、运行和部署你的网站。 网站初始化完成后，源码中将包含一系列可通过包管理器调用的 Docusaurus 脚本： ```json package.json { // ... "scripts": { "docusaurus": "docusaurus", "start": "docusaurus start", "build": "docusaurus build", "swizzle": "docusaurus swizzle", "deploy": "docusaurus deploy", "clear": "docusaurus clear", "serve": "docusaurus serve", "write-translations": "docusaurus write-translations", "write-heading-ids": "docusaurus write-heading-ids" } } ``` Docusaurus CLI 命令​ 以下是 Docusaurus CLI 命令及其用法列表： docusaurus start [siteDir]​ 使用 Webpack Dev Server 在本地构建并运行网站的预览。 选项​ | 名称 | 默认值 | 描述 | | :--- | :--- | :--- | | --port | 3000 | 指定开发服务器的端口。 | | --host | localhost | 指定使用的主机。例如，若希望外部可访问服务器，可使用 --host 0.0.0.0。 | | --hot-only | false | 启用热模块替换（HMR），构建失败时不进行页面刷新回退。更多信息见此处。 | | --no-open | false | 不在浏览器中自动打开页面。 | | --config | undefined | Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js | | --poll [optionalIntervalMs] | false | 在文件监视无法工作的环境中，使用文件轮询代替监视以实现热重载。更多信息见此处。 | | --no-minify | false | 构建网站时不压缩 JS/CSS 包。 | info 请注意，某些功能（例如锚点链接）在开发模式下可能无法正常工作。在生产环境中这些功能将按预期工作。 通过网络进行开发 在从远程服务器或虚拟机（如 GitHub Codespaces）转发 3000 端口时，可以将开发服务器运行在 0.0.0.0 上，使其监听本地 IP。 ```bash npm yarn pnpm bun npm run start -- --host 0.0.0.0 yarn run start --host 0.0.0.0 pnpm run start --host 0.0.0.0 bun run start --host 0.0.0.0 ``` 启用 HTTPS​ 获取证书的方式有多种，这里以 mkcert 为例。 运行 mkcert localhost 生成 localhost.pem 和 localhost-key.pem 运行 mkcert -install 将证书安装到信任存储中，并重启浏览器 使用 Docusaurus 的 HTTPS 环境变量启动应用： ```bash HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start ``` 打开 https://localhost:3000/ docusaurus build [siteDir]​ 为生产环境编译站点。 选项​ 名称默认值说明--bundle-analyzerfalse使用 webpack bundle analyzer 分析打包产物。--out-dirbuild新输出目录的完整路径，相对于当前工作目录。--configundefinedDocusaurus 配置文件路径，默认为 [siteDir]/docusaurus.config.js--no-minifyfalse构建网站时不压缩 JS/CSS 产物。 info为实现更深度的 CSS 压缩，我们使用了高级 cssnano preset（以及额外的几个 PostCSS 插件）和 clean-css 的 level 2 优化。如果这种高级 CSS 压缩导致 CSS 出错，可以在构建时设置环境变量 USE_SIMPLE_CSS_MINIFIER=true，改用默认 cssnano preset 压缩 CSS。如遇 CSS 压缩的 bug，请提交 issue。设置环境变量 SKIP_HTML_MINIFICATION=true 可以跳过 HTML 压缩。 docusaurus swizzle [themeName] [componentName] [siteDir]​ Swizzle（弹出并自定义）主题组件。 npmYarnpnpmBunnpm run swizzle [themeName] [componentName] [siteDir]

# 示例（省略 siteDir 表示当前目录）
npm run swizzle @docusaurus/theme-classic Footer -- --eject
yarn swizzle [themeName] [componentName] [siteDir]

# 示例（省略 siteDir 表示当前目录）
yarn swizzle @docusaurus/theme-classic Footer --eject
pnpm run swizzle [themeName] [componentName] [siteDir]

# 示例（省略 siteDir 表示当前目录）
pnpm run swizzle @docusaurus/theme-classic Footer --eject
bun run swizzle [themeName] [componentName] [siteDir]

# 示例（省略 siteDir 表示当前目录）
bun run swizzle @docusaurus/theme-classic Footer --eject
swizzle CLI 是交互式命令，会引导你完成整个主题定制流程。 选项 themeName：要基于的主题名称。 componentName：要定制的主题组件名称。 --list：列出可定制的主题组件。 --eject：将主题组件代码提取到本地项目中。 --wrap：包装现有的主题组件。 --danger：允许立即定制不安全组件。 --typescript：定制 TypeScript 版本的组件。 --config：Docusaurus 配置文件路径，默认值为 [siteDir]/docusaurus.config.js。 警告：不安全组件因内部重构导致出现破坏性变更的风险更高。 docusaurus deploy [siteDir] 使用 GitHub Pages 部署网站。更多详情请查阅部署文档。 选项 --out-dir：默认值为 build。指定新的输出目录的完整路径，相对于当前工作区。 --skip-build：默认值为 false。跳过构建步骤直接部署网站。在使用自定义部署脚本时可能有用。 --config：默认值为 undefined。Docusaurus 配置文件路径，默认值为 [siteDir]/docusaurus.config.js。 docusaurus serve [siteDir] 在本地运行已构建的网站。 --port：默认值为 3000。指定使用的端口。 --dir：默认值为 build。输出目录的完整路径，相对于当前工作区。 --build：默认值为 false。在运行服务前先构建网站。 --config：默认值为 undefined。Docusaurus 配置文件路径，默认值为 [siteDir]/docusaurus.config.js。 --host：默认值为 localhost。指定主机地址。例如，若希望服务器对外部可访问，可使用 --host 0.0.0.0。 --no-open：默认值在本地为 false，在 CI 环境中为 true。不自动打开浏览器窗口访问服务器地址。 docusaurus clear [siteDir] 清除 Docusaurus 站点生成的资源、缓存和构建产物。 建议在报告 Bug、升级版本或遇到 Docusaurus 站点问题时运行此命令。 docusaurus write-translations [siteDir] 写入需要进行翻译的 JSON 翻译文件。 默认情况下，文件写入到 website/i18n// 目录中。 --locale：默认值为 。定义写入翻译 JSON 文件的目标语言包文件夹。 --override：默认值为 false。覆盖现有的翻译消息。 --config：默认值为 undefined。Docusaurus 配置文件路径，默认值为 [siteDir]/docusaurus.config.js。 --messagePrefix：默认值为 ''。为每条翻译消息添加前缀，以便高亮显示未翻译的字符串。 docusaurus write-heading-ids [siteDir] [files] 为站点中的 Markdown 文档添加显式的标题 ID。 files：默认为插件使用的所有 MD 文件。指定需要写入标题 ID 的文件。 --maintain-case：默认值为 false。保留标题的大小写，否则全部转换为小写。 --overwrite：默认值为 false。覆盖现有的标题 ID。