Skip to main content
Version: 3.0.1

CLI


Docusaurus 提供了一组脚本来帮助你生成、服务和部署网站。

英Docusaurus provides a set of scripts to help you generate, serve, and deploy your website.

一旦你的网站启动，网站源代码将包含 Docusaurus 脚本，你可以使用包管理器调用这些脚本：

英Once your website is bootstrapped, the website source will contain the Docusaurus scripts that you can invoke with your package manager:

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 命令及其用法的列表：

英Below is a list of Docusaurus CLI commands and their usages:

docusaurus start [siteDir]​

使用 Webpack 开发服务器 在本地构建并提供站点预览。

英Builds and serves a preview of your site locally with Webpack Dev Server.

选项​

名称默认描述
--dev在开发模式下构建，包括完整的 React 错误消息。
--port3000指定开发服务器的端口。
--hostlocalhost指定要使用的主机。 例如，如果你希望外部可以访问你的服务器，则可以使用 --host 0.0.0.0。
--hot-onlyfalse启用热模块替换，无需刷新页面，作为构建失败时的后备方案。 更多信息 此处。
--no-openfalse不要在浏览器中自动打开页面。
--configundefinedDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--poll [optionalIntervalMs]false使用文件轮询而不是监视实时重新加载，作为监视不起作用的环境中的后备措施。 更多信息 此处。
--no-minifyfalse在不最小化 JS/CSS 打包的情况下构建网站。
信息

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

英Please note that some functionality (for example, anchor links) will not work in development. The functionality will work as expected in production.

网络开发

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

英When forwarding port 3000 from a remote server or VM (e.g. GitHub Codespaces), you can run the dev server on 0.0.0.0 to make it listen on the local IP.

npm run start -- --host 0.0.0.0

启用 HTTPS​

获得证书的方法有多种。 我们将以 mkcert 为例。

英There are multiple ways to obtain a certificate. We will use mkcert as an example.

  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]​

编译你的网站以进行生产。

英Compiles your site for production.

选项​

名称默认描述
--bundle-analyzerfalse使用 webpack 打包分析器 分析你的打包包。
--out-dirbuild新输出目录相对于当前工作区的完整路径。
--configundefinedDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--no-minifyfalse在不最小化 JS/CSS 打包的情况下构建网站。
信息

为了对 CSS 包进行高级缩小，我们使用 高级 cssnano 预设（以及其他几个 PostCSS 插件）和 clean-css 的 2 级优化。 如果由于这种高级 CSS 缩小，你发现 CSS 损坏，请使用环境变量 USE_SIMPLE_CSS_MINIFIER=true 构建你的网站，以使用 默认 cssnano 预设 缩小 CSS。 如果你遇到 CSS 缩小错误，请 填写一个问题。

英For advanced minification of CSS bundle, we use the advanced cssnano preset (along with additional several PostCSS plugins) and level 2 optimization of clean-css. If as a result of this advanced CSS minification you find broken CSS, build your website with the environment variable USE_SIMPLE_CSS_MINIFIER=true to minify CSS with the default cssnano preset. Please fill out an issue if you experience CSS minification bugs.

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

英You can skip the HTML minification with the environment variable SKIP_HTML_MINIFICATION=true.

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

Swizzle 一个主题组件来定制它。

英Swizzle a theme component to customize it.

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

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

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

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

选项​

名称描述
themeName要混合的主题的名称。
componentName要混合的主题组件的名称。
--list可用于调配的显示组件
--ejectEject 主题组件
--wrap裹 主题组件
--danger允许立即混合不安全的组件
--typescriptSwizzle TypeScript 变体组件
--configdocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
警告

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

英Unsafe components have a higher risk of breaking changes due to internal refactorings.

docusaurus deploy [siteDir]​

使用 GitHub 页面 部署你的站点。 查看 deployment 上的文档了解更多详细信息。

英Deploys your site with GitHub Pages. Check out the docs on deployment for more details.

选项​

名称默认描述
--out-dirbuild新输出目录相对于当前工作区的完整路径。
--skip-buildfalse部署网站而不构建它。 使用自定义部署脚本时这可能很有用。
--configundefinedDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]​

在本地提供你构建的网站。

英Serve your built website locally.

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

docusaurus clear [siteDir]​

清除 Docusaurus 站点生成的资源、缓存、构建工件。

英Clear a Docusaurus site's generated assets, caches, build artifacts.

我们建议在报告错误之前、升级版本之后或在 Docusaurus 站点出现问题时运行此命令。

英We recommend running this command before reporting bugs, after upgrading versions, or anytime you have issues with your Docusaurus site.

docusaurus write-translations [siteDir]​

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

英Write the JSON translation files that you will have to translate.

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

英By default, the files are written in website/i18n/<defaultLocale>/....

名称默认描述
--locale<defaultLocale>定义要在其中写入 JSON 文件翻译的语言环境文件夹
--overridefalse覆盖现有翻译消息
--configundefinedDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--messagePrefix''允许为每条翻译消息添加前缀，以帮助你高亮未翻译的字符串

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

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

英Add explicit heading IDs to the Markdown documents of your site.

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