CLI

Docusaurus 提供了帮助你生成并部署网站的脚本。

网站初始化时，就会自带一系列 Docusaurus 脚本，你可以用包管理器调用：

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 开发服务器 在本地构建并提供站点预览。

选项

参数	默认值	描述
--port	3000	指定开发服务器端口。
--host	localhost	指定绑定的主机。 比如，如果你想让开发服务器可以从外部访问，你可以用 --host 0.0.0.0。
--locale		指定要使用的站点本地化设置。
--hot-only	false	在构建失败时，启用无需手动刷新的热模块替换作为后备选项。 更多信息在这里查阅。
--no-open	false	禁用在浏览器中自动打开页面。
--config	undefined	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]	false	在无法监听文件系统的环境中，使用文件系统轮询而不是监听作为实时重载的替代方案。 更多信息在这里查阅。
--no-minify	false	在不压缩 JS/CSS 的情况下构建站点。
--https	false	以自签名证书通过 HTTPS 启动开发站点。 当参数中同时有 --ssl-cert 与 --ssl-key 时，也默认指定此参数。
--ssl-cert	undefined	TLS 证书文件的路径（默认启用 HTTPS）。
--ssl-key	undefined	TLS 私钥文件的路径（默认启用 HTTPS）。

信息

请注意，某些功能，比如锚点链接，在开发环境中无法使用。 但这些功能会在生产环境中正常工作。

通过远程网络开发

当从远程服务器或虚拟机转发端口 3000 时（比如通过 GitHub Codespaces），你可以把开发服务器运行在 0.0.0.0 上，让它监听本地 IP。

npm

npm run start -- --host 0.0.0.0

Yarn

yarn run start --host 0.0.0.0

pnpm

pnpm run start --host 0.0.0.0

Bun

bun run start --host 0.0.0.0

启用 HTTPS

获取证书有很多方法。 我们将用 mkcert 作为示例。

1. 运行 mkcert localhost 来生成 localhost.pem 和 localhost-key.pem

2. 运行 mkcert -install，把证书安装到你的 trust store，然后重启浏览器

3. 用如下 Docusaurus HTTPS 命令行选项启动应用：

npm

npm run start -- --ssl-cert localhost.pem --ssl-key localhost-key.pem

Yarn

yarn run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

pnpm

pnpm run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

Bun

bun run start --ssl-cert localhost.pem --ssl-key localhost-key.pem

4. 打开 https://localhost:3000/

自签名证书

使用 --https 选项来自动生成自签名证书，并以 HTTPS 托管开发站点。

npm

npm run start -- --https

Yarn

yarn run start --https

pnpm

pnpm run start --https

Bun

bun run start --https

docusaurus build [siteDir]

为你的网站做生产构建。

选项

参数	默认值	描述
--dev		在开发模式下生成站点，包含完整的 React 错误消息。
--bundle-analyzer	false	使用 webpack 包分析器来分析你的包。
--out-dir	build	输出目录的完整路径，相对于当前工作区。
--config	undefined	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--locale		通过指定的本地化语言构建站点。 如果不指定，所有的已知本地化语言都将会被构建。
--no-minify	false	在不压缩 JS/CSS 的情况下构建站点。

信息

对 CSS 包的高级压缩，我们使用高级 cssnano 预设（以及几个其他的 PostCSS 插件）和 clean-css 的二级优化来完成。 若这个高级压缩损坏了 CSS，可以用环境变量 USE_SIMPLE_CSS_MINIFIER=true 构建网站，来使用默认的 cssnano 预设。 如果你遇到了 CSS 压缩的 bug，请提出 issue。

你可以通过环境变量 SKIP_HTML_MINIFICATION=true 来跳过 HTML 压缩。

docusaurus swizzle [themeName] [componentName] [siteDir]

Swizzle a theme component to customize it.

npm

npm run swizzle [themeName] [componentName] [siteDir]

# 示例（不提供 siteDir 会被自动定向到当前路径）
npm run swizzle @docusaurus/theme-classic Footer -- --eject

Yarn

yarn swizzle [themeName] [componentName] [siteDir]

# 示例（不提供 siteDir 会被自动定向到当前路径）
yarn swizzle @docusaurus/theme-classic Footer --eject

pnpm

pnpm run swizzle [themeName] [componentName] [siteDir]

# 示例（不提供 siteDir 会被自动定向到当前路径）
pnpm run swizzle @docusaurus/theme-classic Footer --eject

Bun

bun run swizzle [themeName] [componentName] [siteDir]

# 示例（不提供 siteDir 会被自动定向到当前路径）
bun run swizzle @docusaurus/theme-classic Footer --eject

The swizzle CLI is interactive and will guide you through the whole swizzle process.

选项

参数	描述
themeName	要 swizzle 的主题名。
componentName	要 swizzle 的主题组件名。
--list	显示所有可 swizzle 的组件名
--eject	Eject the theme component
--wrap	Wrap the theme component
--danger	允许 swizzle 不安全的组件
--typescript	Swizzle TypeScript 组件变种
--javascript	Swizzle the JavaScript variant component
--config	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js

警告

不安全组件很容易因为内部重构而产生破坏性变更。

docusaurus deploy [siteDir]

使用 GitHub Pages 部署你的站点。 Check out the docs on deployment for more details.

选项

参数	默认值	描述
--locale		通过指定的本地化语言部署站点。 如果不指定，所有的已知本地化语言都将会被部署。
--out-dir	build	输出目录的完整路径，相对于当前工作区。
--skip-build	false	跳过构建直接部署网站。 如果你有自定义的部署脚本，可以用这个选项。
--target-dir	.	要部署到的目标目录的路径。
--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/\<defaultLocale>/...。

参数	默认值	描述
--locale	\<defaultLocale>	定义你想要写入 JSON 文件的语言文件夹。
--override	false	覆盖现有的翻译内容。
--config	undefined	Docusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--messagePrefix	''	允许为每个翻译信息添加一个前缀，以突出显示未翻译的字符串。

docusaurus write-heading-ids [siteDir] [files]

为你站点的 Markdown 文件加上显式的标题 ID。

参数	默认值	描述
files	所有被插件使用的 MD 文件	你想要写入标题 ID 的文件。
--syntax	classic	选择标题 ID 的语法：classic ({#id}) 或者 mdx-comment ({/* #id */})。
--migrate	false	如果现有标题 ID 的语法不同，将它们迁移到 --syntax 指定的语法。
--overwrite	false	覆盖现有的标题 ID，然后从标题文本中重新生成。
--maintain-case	false	保留标题的大小写，否则会全部变成小写。