跳到主要内容

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

选项​

名称默认值描述
--port3000指定开发服务器的端口。
--hostlocalhost指定要使用的主机。例如，如果你希望你的服务器可以从外部访问，可以使用 --host 0.0.0.0。
--locale指定要使用的站点语言环境。
--hot-onlyfalse在构建失败时启用热模块替换，而不刷新页面作为后备方案。更多信息请在此处查看。
--no-openfalse不在浏览器中自动打开页面。
--configundefined道格龙（Docusaurus）配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]false在监视文件不工作的环境中使用文件轮询而不是监视来进行实时重新加载。更多信息请在此处查看。
--no-minifyfalse构建网站时不压缩 JS/CSS 包。
信息

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

通过网络进行开发

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

npm 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
  1. 打开 https://localhost:3000/

docusaurus build [siteDir]​

为生产环境编译你的网站。

选项​

名称默认值描述
--dev在开发模式下构建网站，包括完整的 React 错误消息。
--bundle-analyzerfalse使用 webpack bundle analyzer 分析你的包。
--out-dirbuild新输出目录的完整路径，相对于当前工作区。
--configundefined道格龙（Docusaurus）配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--locale以指定的语言环境构建站点。如果未指定，则构建所有已知的语言环境。
--no-minifyfalse构建网站时不压缩 JS/CSS 包。
信息

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

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

docusaurus swizzle [themeName] [componentName] [siteDir]​

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

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

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

swizzle CLI 是交互式的，它将指导你完成整个 swizzle 过程。

选项​

名称描述
themeName要 swizzle 的主题名称。
componentName要 swizzle 的主题组件名称。
--list显示可供 swizzle 的组件
--ejectEject 主题组件
--wrapWrap 主题组件
--danger允许立即 swizzle 不安全的组件
--typescriptSwizzle TypeScript 变体组件
--config道格龙（Docusaurus）配置文件的路径，默认为 [siteDir]/docusaurus.config.js
注意

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

docusaurus deploy [siteDir]​

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

选项​

名称默认值描述
--locale以指定的语言环境部署站点。如果未指定，则部署所有已知的语言环境。
--out-dirbuild新输出目录的完整路径，相对于当前工作区。
--skip-buildfalse部署网站而不构建它。这在使用自定义部署脚本时可能很有用。
--target-dir.要部署到的目标目录的路径。
--configundefined道格龙（Docusaurus）配置文件的路径，默认为 [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]​

在本地运行你构建好的网站。

名称默认值描述
--port3000使用指定的端口
--dirbuild输出目录的完整路径，相对于当前工作区
--buildfalse在运行前构建网站
--configundefined道格龙（Docusaurus）配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--hostlocalhost指定要使用的主机。例如，如果你希望你的服务器可以从外部访问，可以使用 --host 0.0.0.0。
--no-open本地为 false，CI 中为 true不在浏览器窗口中打开服务器位置。

docusaurus clear [siteDir]​

清除道格龙（Docusaurus）网站生成的资源、缓存、构建产物。

我们建议在报告错误、升级版本或任何时候你的道格龙（Docusaurus）网站出现问题时运行此命令。

docusaurus write-translations [siteDir]​

写入你需要翻译的 JSON 翻译文件。

默认情况下，文件写入 website/i18n/<defaultLocale>/...。

名称默认值描述
--locale<defaultLocale>定义你想要写入翻译 JSON 文件的语言环境文件夹
--overridefalse覆盖现有的翻译消息
--configundefined道格龙（Docusaurus）配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--messagePrefix''允许在每个翻译消息前添加前缀，以帮助你突出显示未翻译的字符串

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

向你网站的 Markdown 文档添加明确的标题 ID。

名称默认值描述
files插件使用的所有 MD 文件你希望写入标题 ID 的文件。
--maintain-casefalse保留标题的大小写，否则全部转换为小写。
--overwritefalse覆盖现有的标题 ID。