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 commands

以下是 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.

选项

¥Options

名称	默认	描述
--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 打包的情况下构建网站。

信息

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

¥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

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

¥Enabling 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

   ¥Run mkcert localhost to generate localhost.pem + localhost-key.pem

2. 运行 mkcert -install 将证书安装到你的信任存储中，然后重新启动浏览器

   ¥Run mkcert -install to install the cert in your trust store, and restart your browser

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

   ¥Start the app with Docusaurus HTTPS env variables:

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

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

   ¥Open https://localhost:3000/

docusaurus build [siteDir]

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

¥Compiles your site for production.

选项

¥Options

名称	默认	描述
--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 的 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

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 是交互式的，将指导你完成整个 调配过程。

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

选项

¥Options

名称	描述
themeName	要混合的主题的名称。
componentName	要混合的主题组件的名称。
--list	可用于调配的显示组件
--eject	Eject 主题组件
--wrap	裹 主题组件
--danger	允许立即混合不安全的组件
--typescript	Swizzle TypeScript 变体组件
--config	docusaurus 配置文件的路径，默认为 [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.

选项

¥Options

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

docusaurus serve [siteDir]

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

¥Serve your built website locally.

名称	默认	描述
--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 站点生成的资源、缓存、构建工件。

¥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 文件翻译的语言环境文件夹
--override	false	覆盖现有翻译消息
--config	undefined	Docusaurus 配置文件的路径，默认为 [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-case	false	保留标题的大小写，否则全部小写。
--overwrite	false	覆盖现有的标题 ID。