Skip to main content
版本：Canary 🚧

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

选项​

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

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

通过远程网络开发

当从远程服务器或虚拟机转发端口 3000 时（比如通过 GitHub Codespaces），你可以把开发服务器运行在 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，把证书安装到你的 trust store，然后重启浏览器

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

npm run start -- --ssl-cert localhost.pem --ssl-key localhost-key.pem
  1. 打开 https://localhost:3000/
自签名证书

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

npm run start -- --https

docusaurus build [siteDir]​

为你的网站做生产构建。

选项​

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

CSS bundles are minified with Lightning CSS, using your site's Browserslist config as targets. Please fill out an issue if you experience CSS minification bugs.

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

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

Swizzle a theme component to customize it.

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

# 示例（不提供 siteDir 会被自动定向到当前路径）
npm 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 的组件名
--ejectEject the theme component
--wrapWrap the theme component
--danger允许 swizzle 不安全的组件
--typescriptSwizzle TypeScript 组件变种
--javascriptSwizzle the JavaScript variant component
--configDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
警告

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

docusaurus deploy [siteDir]​

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

选项​

参数默认值描述
--locale通过指定的本地化语言部署站点。如果不指定，所有的已知本地化语言都将会被部署。
--out-dirbuild输出目录的完整路径，相对于当前工作区。
--skip-buildfalse跳过构建直接部署网站。如果你有自定义的部署脚本，可以用这个选项。
--target-dir.要部署到的目标目录的路径。
--configundefinedDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js

docusaurus serve [siteDir]​

在本地开启网站服务。

参数默认值描述
--port3000使用指定端口。
--dirbuild输出目录相对于当前工作区的完整路径。
--buildfalse在开启服务前构建网站。
--configundefinedDocusaurus 配置文件的路径，默认为 [siteDir]/docusaurus.config.js
--hostlocalhost指定绑定的主机。比如，如果你想让开发服务器可以从外部访问，你可以用 --host 0.0.0.0。
--no-open本地为 false，CI 中为 true`不要打开浏览器窗口。

HTTP caching​

docusaurus serve tells browsers how to cache each response with the Cache-Control header:

ResponsesCache-ControlBrowser behavior
Files in /assets/public, max-age=31536000, immutableReuses the file for one year, without asking the server.
Everything else: pages, other static files, redirects, errorsno-cacheAsks the server before each reuse. The server answers 304 Not Modified when the file content didn't change, using its ETag.

The bundler adds a content hash to the names of the files it emits in /assets/ (JavaScript, CSS, images, fonts…): when the content of a file changes, its URL changes too.

The other files keep their URLs from one build to the next. Revalidating them ensures you always see your latest build, and the redirects of your current baseUrl and trailingSlash config, even after serving another site on the same port.

The /assets/ folders of the other locales of an i18n site, like /fr/assets/, are revalidated like the other files.

警告

Don't put files in an assets folder of your static directories, like static/assets/. They are copied to /assets/ without a content hash, so browsers can keep using an outdated version for one year.

docusaurus clear [siteDir]​

清除 Docusaurus 网站生成的资源、缓存、构建产物。

我们建议在报告 bug 之前、在升级版本之后，或在你使用 Docusaurus 网站遇到任何问题时运行此命令。

docusaurus write-translations [siteDir]​

写入 JSON 翻译文件，你需要翻译它们。

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

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

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

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

参数默认值描述
files所有被插件使用的 MD 文件你想要写入标题 ID 的文件。
--syntaxInferred选择标题 ID 的语法：classic ({#id}) 或者 mdx-comment ({/* #id */})。 By default, it uses classic for files compiled as CommonMark, and mdx-comment for files compiled as MDX, according to the markdown.format config option.
--migratefalse如果现有标题 ID 的语法不同，将它们迁移到 --syntax 指定的语法。
--overwritefalse覆盖现有的标题 ID，然后从标题文本中重新生成。
--maintain-casefalse保留标题的大小写，否则会全部变成小写。