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 Dev Server 在本地构建并提供您网站的预览。

选项

名称	默认值	描述
--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 包进行最小化。

信息

请注意，某些功能（例如，锚点链接）在开发环境中可能无法正常工作。这些功能在生产环境中会按预期工作。

通过网络进行开发

当从远程服务器或虚拟机（例如 GitHub Codespaces）转发端口 3000 时，您可以在 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 将证书安装到您的信任存储中，并重启浏览器

3. 使用 Docusaurus HTTPS 环境变量启动应用程序

HTTPS=true SSL_CRT_FILE=localhost.pem SSL_KEY_FILE=localhost-key.pem yarn start

4. 打开 https://:3000/

docusaurus build [siteDir]

编译您的网站以用于生产环境。

选项

名称	默认值	描述
--dev		以开发模式构建网站，包括完整的 React 错误消息。
--bundle-analyzer	false	使用 webpack bundle analyzer 分析您的打包。
--out-dir	build	新输出目录的完整路径，相对于当前工作区。
--config	undefined	Docusaurus 配置文件路径，默认为 [siteDir]/docusaurus.config.js
--locale		以指定区域设置构建网站。如果未指定，则构建所有已知区域设置。
--no-minify	false	构建网站时不对 JS/CSS 包进行最小化。

信息

对于 CSS 包的高级最小化，我们使用 高级 cssnano 预设（以及其他几个 PostCSS 插件）和 clean-css 的二级优化。如果由于这种高级 CSS 最小化导致您发现 CSS 损坏，请使用环境变量 USE_SIMPLE_CSS_MINIFIER=true 构建您的网站，以便使用 默认 cssnano 预设 最小化 CSS。如果您遇到 CSS 最小化错误，请提交一个 issue。

您可以使用环境变量 SKIP_HTML_MINIFICATION=true 跳过 HTML 最小化。

docusaurus swizzle [themeName] [componentName] [siteDir]

Swizzle 一个主题组件以自定义它。

npm

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

# Example (leaving out the siteDir to indicate this directory)
npm run swizzle @docusaurus/theme-classic Footer -- --eject

Yarn

yarn swizzle [themeName] [componentName] [siteDir]

# Example (leaving out the siteDir to indicate this directory)
yarn swizzle @docusaurus/theme-classic Footer --eject

pnpm

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

# Example (leaving out the siteDir to indicate this directory)
pnpm run swizzle @docusaurus/theme-classic Footer --eject

Bun

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

# Example (leaving out the siteDir to indicate this directory)
bun run swizzle @docusaurus/theme-classic Footer --eject

swizzle CLI 是交互式的，将引导您完成整个 swizzle 过程。

选项

名称	描述
themeName	要 swizzle 的主题名称。
componentName	要 swizzle 的主题组件名称。
--list	显示可用于 swizzling 的组件
--eject	弹出主题组件
--wrap	包裹主题组件
--danger	允许立即 swizzle 不安全的组件
--typescript	Swizzle TypeScript 变体组件
--config	Docusaurus 配置文件路径，默认为 [siteDir]/docusaurus.config.js

警告

不安全的组件由于内部重构，存在更高的破坏性更改风险。

docusaurus deploy [siteDir]

使用 GitHub Pages 部署您的网站。有关更多详细信息，请查阅部署文档。

选项

名称	默认值	描述
--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 本地，true 在 CI	不要在浏览器中打开服务器位置的窗口。

docusaurus clear [siteDir]

清除 Docusaurus 网站的生成资产、缓存和构建工件。

我们建议在报告错误、升级版本后或任何时候您的 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]

将显式标题 ID 添加到您网站的 Markdown 文档中。

名称	默认值	描述
files	插件使用的所有 MD 文件	要写入标题 ID 的文件。
--maintain-case	false	保持标题的大小写，否则全部转换为小写。
--overwrite	false	覆盖现有标题 ID。