部署

若要为你的网站构建用于生产环境的静态文件，请运行：

npm

npm run build

Yarn

yarn build

pnpm

pnpm run build

Bun

bun run build

该命令执行完毕后，静态文件将被生成到 build 目录中。

备注

道格龙（Docusaurus）的唯一职责是构建你的网站并将静态文件输出到 build 目录。

接下来，你需要自行选择如何托管这些静态文件。

你可以将你的网站部署到各种静态网站托管服务，例如 Vercel、GitHub Pages、Netlify、Render 以及 Surge。

道格龙（Docusaurus）网站是静态渲染的，通常在没有 JavaScript 的情况下也能正常工作！

配置

为了优化路由并从正确的位置提供文件，你需要在 docusaurus.config.js 文件中配置以下参数：

名称	描述
url	你网站的 URL。对于部署在 https://my-org.com/my-project/ 的网站，url 就是 https://my-org.com/。
baseUrl	你项目的基准 URL，需要以斜杠结尾。对于部署在 https://my-org.com/my-project/ 的网站，baseUrl 就是 /my-project/。

在本地测试构建产物

在将网站部署到生产环境之前，于本地进行测试是至关重要的一步。道格龙（Docusaurus）为此提供了一个 docusaurus serve 命令：

npm

npm run serve

Yarn

yarn serve

pnpm

pnpm run serve

Bun

bun run serve

默认情况下，这将在 http://localhost:3000/ 加载你的网站。

URL 结尾斜杠配置

道格龙（Docusaurus）提供了一个 trailingSlash 配置，允许你自定义 URL/链接格式和最终生成的文件名模式。

通常情况下，默认值就能很好地工作。但遗憾的是，每个静态托管服务提供商都有不同的行为模式，将完全相同的站点部署到不同的托管服务上可能会产生迥异的结果。因此，根据你所选的托管服务，调整此配置可能会非常有用。

提示

可以参考 slorber/trailing-slash-guide 这个指南来更好地理解你所用托管服务的行为，并据此正确配置 trailingSlash。

使用环境变量

将潜在的敏感信息放入环境变量中是一种常见的实践。然而，在一个典型的 道格龙（Docusaurus）网站中，docusaurus.config.js 文件是与 Node.js 环境交互的唯一接口（请参阅我们的架构概览），而其他所有内容（如 MDX 页面、React 组件等）都属于客户端，无法直接访问 process 全局变量。在这种情况下，你可以考虑使用 customFields 将环境变量传递给客户端。

docusaurus.config.js

// 如果你正在使用 dotenv (https://www.npmjs.com/package/dotenv)
import 'dotenv/config';

export default {
  title: '...',
  url: process.env.URL, // 你也可以使用环境变量来控制站点的特定信息
  customFields: {
    // 在这里放置你的自定义环境信息
    teamEmail: process.env.EMAIL,
  },
};

home.jsx

import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function Home() {
  const {
    siteConfig: {customFields},
  } = useDocusaurusContext();
  return <div>通过 {customFields.teamEmail} 联系我们！</div>;
}

选择托管服务提供商

常见的托管方案有以下几种：

• 使用像 Apache2 或 Nginx 这样的 HTTP 服务器进行自主托管。
• 使用 Jamstack 供应商（例如 Netlify 和 Vercel）。我们会以它们作为参考，但同样的逻辑也适用于其他供应商。
• 使用 GitHub Pages（从定义上讲，它也属于 Jamstack，但我们将其分开比较）。

如果你不确定该如何选择，可以问自己以下几个问题：

我愿意为此投入多少资源（金钱、人力、时间等）？

• 🔴 自主托管：需要网络、Linux 及 Web 服务器管理方面的经验。这是最困难的选项，需要最多的时间来成功管理。在费用方面，云服务几乎从不免费，而购买和部署本地服务器的成本可能更高。
• 🟢 Jamstack 供应商：它们可以帮助你在极短的时间内建立一个可用的网站，并提供易于配置的服务端重定向等功能。许多供应商即使是免费计划也提供非常慷慨的构建时长额度，你几乎永远不会超出。然而，免费计划总有其限制，一旦达到这些限制就需要付费。详情请查看你所选供应商的定价页面。
• 🟡 GitHub Pages：其部署流程设置起来可能比较繁琐（证据：请看部署到 GitHub Pages 章节的篇幅！）。然而，这项服务（包括构建和部署）对于公共仓库始终是免费的，并且我们有详细的说明来帮助你完成设置。

我需要多大程度的服务端定制化？

• 🟢 自主托管：你可以完全控制服务器的配置。你可以配置虚拟主机以根据请求 URL 提供不同的内容，可以实现复杂的服务端重定向，可以实施身份验证等等。如果你需要大量服务端功能，自主托管是最佳选择。
• 🟡 Jamstack：通常提供一些服务端配置选项（例如 URL 格式化（结尾斜杠）、服务端重定向等）。
• 🔴 GitHub Pages：除了强制执行 HTTPS 和设置 CNAME 记录外，不提供任何服务端配置。

我是否需要一个对协作友好的部署流程？

• 🟡 自主托管：虽然可以利用像 Netlify 那样的持续部署功能，但这需要更多繁重的工作。通常，你会指定一个特定的人来管理部署，其工作流程也不像另外两个选项那样基于 Git。
• 🟢 Netlify 和 Vercel：为每个 pull request 提供部署预览，这对于团队在合并到生产环境之前审查工作非常有用。你还可以管理一个具有不同成员访问权限的部署团队。
• 🟡 GitHub Pages：无法以一种简洁明了的方式实现部署预览。一个仓库只能关联一个站点部署。但另一方面，你可以控制谁对站点的部署拥有写权限。

没有所谓的"万能药"。在做出选择之前，你需要权衡自己的需求和资源。

自主托管

道格龙（Docusaurus）可以通过 docusaurus serve 命令进行自主托管。使用 --port 更改端口，使用 --host 更改主机。

npm

npm run serve -- --build --port 80 --host 0.0.0.0

Yarn

yarn serve --build --port 80 --host 0.0.0.0

pnpm

pnpm run serve --build --port 80 --host 0.0.0.0

Bun

bun run serve --build --port 80 --host 0.0.0.0

注意

与静态托管服务提供商或 CDN 相比，这并非最佳选择。

注意

在接下来的章节中，我们将介绍几个常见的托管服务提供商，以及如何配置它们以最高效地部署 道格龙（Docusaurus）网站。道格龙（Docusaurus）与这些服务没有任何关联，提供这些信息仅为方便起见。其中一些内容由第三方提供，近期的 API 变更可能尚未在我们这边得到反映。如果你发现内容过时，欢迎提交 PR。

由于我们只能在尽力而为的基础上提供这些内容，我们已停止接受添加新的托管选项的 PR。但是，你可以将你的文章发布在其他网站上（例如你的博客，或提供商的官方网站），然后请求我们将链接包含进来。

部署到 Netlify

要将你的 道格龙（Docusaurus）网站部署到 Netlify，首先请确保正确配置了以下选项：

docusaurus.config.js

export default {
  url: 'https://docusaurus-2.netlify.app', // 你的网站 URL，末尾不带斜杠
  baseUrl: '/', // 你网站相对于仓库根目录的基准目录
  // ...
};

然后，通过 Netlify 创建你的网站。

在设置网站时，请按如下方式指定构建命令和目录：

• 构建命令：npm run build
• 发布目录：build

如果你在创建时没有配置这些构建选项，你仍然可以在网站创建后进入 "Site settings" -> "Build & deploy" 进行设置。

一旦使用上述选项正确配置，你的网站应该能够成功部署，并在每次合并到部署分支（默认为 main）时自动重新部署。

注意

有些 道格龙（Docusaurus）网站会将 docs 文件夹放在 website 文件夹之外（很可能以前是 Docusaurus v1 的网站）：

repo           # git 仓库根目录
├── docs       # MD 文件
└── website    # Docusaurus 项目根目录

如果你决定使用 website 文件夹作为 Netlify 的基准目录，那么当你更新 docs 文件夹时，Netlify 将不会触发构建。你需要配置一个自定义的 ignore 命令：

website/netlify.toml

[build]
  ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"

注意

默认情况下，Netlify 会在 道格龙（Docusaurus）的 URL 末尾添加斜杠。

建议禁用 Netlify 的 Post Processing > Asset Optimization > Pretty Urls 设置，以防止 URL 被小写化、不必要的重定向和 404 错误。

请务必小心：全局的 Disable asset optimization 复选框存在问题，实际上并不能真正禁用 Pretty URLs 设置。请确保独立地取消勾选它。

如果你希望保留 Netlify 的 Pretty Urls 设置，请相应地调整 道格龙（Docusaurus）的 trailingSlash 配置。

更多信息请参考 slorber/trailing-slash-guide。

部署到 Vercel

将你的 道格龙（Docusaurus）项目部署到 Vercel 将在性能和易用性方面为你带来诸多好处。

要通过 Vercel for Git Integration 部署你的 道格龙（Docusaurus）项目，请确保它已被推送到一个 Git 仓库。

使用 Import Flow 将项目导入到 Vercel。在导入过程中，你会发现所有相关选项都已为你预先配置好；不过，你也可以选择更改这些选项。

项目导入后，所有后续对分支的推送都将生成预览部署 (Preview Deployments)，而所有对生产分支 (Production Branch)（通常是 "main" 或 "master"）的更改都将产生生产部署 (Production Deployment)。

部署到 GitHub Pages

道格龙（Docusaurus）提供了一种简便的方式来发布到 GitHub Pages，这是每个 GitHub 仓库都免费提供的功能。

概览

通常，一个发布过程会涉及两个仓库（或至少两个分支）：一个包含源文件的分支，另一个包含用于通过 GitHub Pages 提供服务的构建输出的分支。在下面的教程中，它们将分别被称为**"源分支"和"部署分支"**。

每个 GitHub 仓库都关联一个 GitHub Pages 服务。如果部署仓库名为 my-org/my-project（其中 my-org 是组织或用户名），则部署后的网站将出现在 https://my-org.github.io/my-project/。如果部署仓库名为 my-org/my-org.github.io（即组织 GitHub Pages 仓库），则网站将出现在 https://my-org.github.io/。

信息

如果你想为 GitHub Pages 使用自定义域名，请在 static 目录中创建一个 CNAME 文件。static 目录中的任何内容都将被复制到 build 目录的根部以供部署。使用自定义域名时，你应该可以将 baseUrl 从 '/projectName/' 改回 '/'，并将 url 设置为你的自定义域名。

你可以参考 GitHub Pages 的文档 用户、组织和项目页面 了解更多详情。

GitHub Pages 会从默认分支（通常是 master / main）或 gh-pages 分支的根目录或 /docs 文件夹中获取可部署的文件（即 docusaurus build 的输出）。你可以在你的仓库中通过 Settings > Pages 来配置这一点。这个分支将被称作"部署分支"。

我们提供了一个 docusaurus deploy 命令，可以帮助你用一条命令就将你的网站从源分支部署到部署分支：克隆、构建和提交。

docusaurus.config.js 设置

首先，修改你的 docusaurus.config.js 并添加以下参数：

名称	描述
organizationName	拥有部署仓库的 GitHub 用户或组织。
projectName	部署仓库的名称。
deploymentBranch	部署分支的名称。对于非组织的 GitHub Pages 仓库（即 projectName 不以 .github.io 结尾），它默认为 'gh-pages'。否则，需要作为配置字段或环境变量明确指定。

这些字段也有其对应的环境变量，它们具有更高的优先级：ORGANIZATION_NAME、PROJECT_NAME 和 DEPLOYMENT_BRANCH。

注意

默认情况下，GitHub Pages 会在 道格龙（Docusaurus）的 URL 末尾添加斜杠。建议设置一个 trailingSlash 配置（true 或 false，但不能是 undefined）。

示例：

docusaurus.config.js

export default {
  // ...
  url: 'https://endiliey.github.io', // 你的网站 URL
  baseUrl: '/',
  projectName: 'endiliey.github.io',
  organizationName: 'endiliey',
  trailingSlash: false,
  // ...
};

注意

默认情况下，GitHub Pages 会通过 Jekyll 运行发布的文件。由于 Jekyll 会丢弃任何以下划线 _ 开头的文件，建议你在 static 目录中添加一个名为 .nojekyll 的空文件来禁用 Jekyll。

环境设置

名称	描述
USE_SSH	设置为 true 以使用 SSH 代替默认的 HTTPS 来连接 GitHub 仓库。如果源仓库的 URL 是一个 SSH URL（例如 [email protected]:facebook/docusaurus.git），USE_SSH 会被自动推断为 true。
GIT_USER	对部署仓库有推送权限的 GitHub 账户的用户名。对于你自己的仓库，这通常是你的 GitHub 用户名。如果不使用 SSH，则此项为必需，否则将被忽略。
GIT_PASS	git 用户（由 GIT_USER 指定）的个人访问令牌，用于非交互式部署（例如持续部署）。
CURRENT_BRANCH	源分支。通常，这个分支是 main 或 master，但可以是除了 gh-pages 之外的任何分支。如果未设置此变量，则将使用调用 docusaurus deploy 时所在的当前分支。
GIT_USER_NAME	推送到部署仓库时使用的 git config user.name 的值。
GIT_USER_EMAIL	推送到部署仓库时使用的 git config user.email 的值。

GitHub 企业版实例的运作方式应与 github.com 相同；你只需将组织的 GitHub Enterprise 主机设置为环境变量即可：

名称	描述
GITHUB_HOST	你的 GitHub Enterprise 网站的域名。
GITHUB_PORT	你的 GitHub Enterprise 网站的端口。

部署

最后，要将你的网站部署到 GitHub Pages，请运行：

Bash

GIT_USER=<GITHUB_USERNAME> yarn deploy

Windows

cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"

PowerShell

cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'

注意

从 2021 年 8 月起，GitHub 要求每次命令行登录都使用个人访问令牌 (Personal Access Token) 而不是密码。当 GitHub 提示输入密码时，请输入你的 PAT。更多信息请参阅 GitHub 文档。

或者，你可以使用 SSH (USE_SSH=true) 来登录。

使用 GitHub Actions 触发部署

GitHub Actions 允许你在你的仓库中自动化、定制和执行你的软件开发工作流程。

下面的工作流程示例假设你的网站源代码位于仓库的 main 分支（即_源分支_是 main），并且你的发布源被配置为使用自定义的 GitHub Actions 工作流程进行发布。

我们的目标是：

1. 当一个新的 pull request 被提交到 main 分支时，有一个 action 会确保网站能够成功构建，但实际上并不会部署。这个 job 将被称为 test-deploy。
2. 当一个 pull request 被合并到 main 分支，或者有人直接推送到 main 分支时，网站将被构建并部署到 GitHub Pages。这个 job 将被称为 deploy。

这里有两种使用 GitHub Actions 部署你的文档的方法。请根据你的部署仓库的位置，选择下面相关的标签页：

• 源仓库和部署仓库是同一个仓库。
• 部署仓库是一个远程仓库，与源仓库不同。此场景的说明假设发布源是 gh-pages 分支。

同一仓库

虽然你可以在同一个工作流程文件中定义两个 job，但原始的 deploy 工作流程在 PR 的检查套件状态中将总是被列为"已跳过"，这并不能反映真实状态，也对审查过程没有价值。因此，我们建议将它们作为独立的工作流程来管理。

GitHub Action 文件

添加这两个工作流程文件：

根据你的设置调整参数

如果你的 道格龙（Docusaurus）项目不在你的仓库根目录，你可能需要配置一个默认工作目录，并相应地调整路径。

npm

.github/workflows/deploy.yml

name: 部署到 GitHub Pages

on:
  push:
    branches:
      - main
    # 如果你想进一步定义触发器、路径等，请查阅 gh actions 文档
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: 构建 Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: 安装依赖
        run: npm ci
      - name: 构建网站
        run: npm run build

      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: 部署到 GitHub Pages
    needs: build

    # 授予 GITHUB_TOKEN 所需的权限以进行 Pages 部署
    permissions:
      pages: write # 部署到 Pages
      id-token: write # 验证部署是否来自适当的源

    # 部署到 github-pages 环境
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: 部署到 GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

.github/workflows/test-deploy.yml

name: 测试部署

on:
  pull_request:
    branches:
      - main
    # 如果你想进一步定义触发器、路径等，请查阅 gh actions 文档
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  test-deploy:
    name: 测试部署
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: npm

      - name: 安装依赖
        run: npm ci
      - name: 测试构建网站
        run: npm run build

Yarn

.github/workflows/deploy.yml

name: 部署到 GitHub Pages

on:
  push:
    branches:
      - main
    # 如果你想进一步定义触发器、路径等，请查阅 gh actions 文档
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  build:
    name: 构建 Docusaurus
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn

      - name: 安装依赖
        run: yarn install --frozen-lockfile
      - name: 构建网站
        run: yarn build

      - name: 上传构建产物
        uses: actions/upload-pages-artifact@v3
        with:
          path: build

  deploy:
    name: 部署到 GitHub Pages
    needs: build

    # 授予 GITHUB_TOKEN 所需的权限以进行 Pages 部署
    permissions:
      pages: write # 部署到 Pages
      id-token: write # 验证部署是否来自适当的源

    # 部署到 github-pages 环境
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}

    runs-on: ubuntu-latest
    steps:
      - name: 部署到 GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4

.github/workflows/test-deploy.yml

name: 测试部署

on:
  pull_request:
    branches:
      - main
    # 如果你想进一步定义触发器、路径等，请查阅 gh actions 文档
    # https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on

jobs:
  test-deploy:
    name: 测试部署
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn

      - name: 安装依赖
        run: yarn install --frozen-lockfile
      - name: 测试构建网站
        run: yarn build

远程仓库

跨仓库发布设置起来更困难，因为你需要推送到另一个有权限检查的仓库。我们将使用 SSH 来进行身份验证。

1. 生成一个新的 SSH 密钥。由于此 SSH 密钥将在 CI 中使用，请确保不要输入任何密码短语。
2. 默认情况下，你的公钥应该已创建在 ~/.ssh/id_rsa.pub；否则，请使用你在上一步中提供的名称将你的密钥添加到 GitHub 部署密钥。
3. 使用 pbcopy < ~/.ssh/id_rsa.pub 将密钥复制到剪贴板，并将其作为部署密钥粘贴到部署仓库中。如果命令行对你无效，请复制文件内容。在保存部署密钥之前，请勾选 Allow write access（允许写访问）复选框。
4. 你需要你的私钥作为 GitHub secret 来允许 道格龙（Docusaurus）为你运行部署。
5. 使用 pbcopy < ~/.ssh/id_rsa 复制你的私钥，并在你的源仓库上粘贴一个名为 GH_PAGES_DEPLOY 的 GitHub secret。如果命令行对你无效，请复制文件内容。保存你的 secret。
6. 在 .github/workflows/ 目录中创建你的文档工作流程。在本例中是 deploy.yml 文件。

此时，你应该拥有：

• 设置了 GitHub 工作流程并将私有 SSH 密钥作为 GitHub Secret 的源仓库，以及
• 在 GitHub 部署密钥中设置了公共 SSH 密钥的部署仓库。

GitHub Action 文件

注意

请确保将 [email protected] 替换为你的 GitHub 邮箱，将 gh-actions 替换为你的名字。

此文件假设你正在使用 Yarn。如果你使用 npm，请相应地将 cache: yarn、yarn install --frozen-lockfile、yarn build 更改为 cache: npm、npm ci、npm run build。

.github/workflows/deploy.yml

name: 部署到 GitHub Pages

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

permissions:
  contents: write

jobs:
  test-deploy:
    if: github.event_name != 'push'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn
      - name: 安装依赖
        run: yarn install --frozen-lockfile
      - name: 测试网站构建
        run: yarn build
  deploy:
    if: github.event_name != 'pull_request'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 18
          cache: yarn
      - uses: webfactory/ssh-[email protected]
        with:
          ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
      - name: 部署到 GitHub Pages
        env:
          USE_SSH: true
        run: |
          git config --global user.email "[email protected]"
          git config --global user.name "gh-actions"
          yarn install --frozen-lockfile
          yarn deploy

网站没有正确部署？

推送到 main 分支后，如果你没有在预期的位置看到你的网站发布（例如，它显示"这里没有 GitHub Pages 网站"，或者它显示的是你仓库的 README.md 文件），请尝试以下操作：

• 等待大约三分钟然后刷新。GitHub Pages 可能需要几分钟才能获取到新文件。
• 检查你的仓库登陆页面，看最后一个提交标题旁边是否有一个绿色的小勾，这表示 CI 已通过。如果你看到一个叉，这意味着构建或部署失败了，你应该检查日志以获取更多调试信息。
• 点击那个勾，并确保你看到了一个名为"Deploy to GitHub Pages"的工作流程。像"pages build and deployment / deploy"这样的名字是 GitHub 的默认工作流程，这表示你的自定义部署工作流程根本没有被触发。请确保 YAML 文件被放置在 .github/workflows 文件夹下，并且触发条件设置正确（例如，如果你的默认分支是"master"而不是"main"，你需要更改 on.push 属性）。
• 在你的仓库的 Settings > Pages 下，确保"Source"（这是部署文件的来源，而不是我们术语中的"源文件"）被设置为"gh-pages" + "/" (root)"，因为我们正在使用 gh-pages 作为部署分支。

如果你正在使用自定义域名：

• 如果你正在使用自定义域名，请验证你是否设置了正确的 DNS 记录。请参阅 GitHub Pages 关于配置自定义域名的文档。另外，请注意 DNS 更改可能需要长达 24 小时才能在互联网上传播开。

使用 Travis CI 触发部署

持续集成（CI）服务通常用于在有新提交签入源代码控制时执行例行任务。这些任务可以是运行单元测试和集成测试、自动化构建、将包发布到 npm 以及部署网站更改的任意组合。要自动化你的网站部署，你所需要做的就是在网站更新时调用 yarn deploy 脚本。以下部分将介绍如何使用 Travis CI（一个流行的持续集成服务提供商）来做到这一点。

1. 前往 https://github.com/settings/tokens 并生成一个新的个人访问令牌。在创建令牌时，授予它 repo 范围，以便它拥有所需的权限。
2. 使用你的 GitHub 账户，将 Travis CI 应用添加到你想要激活的仓库。
3. 打开你的 Travis CI 仪表板。URL 看起来像 https://travis-ci.com/USERNAME/REPO，然后导航到你的仓库的 More options > Setting > Environment Variables 部分。
4. 创建一个名为 GH_TOKEN 的新环境变量，其值为你新生成的令牌，然后再创建 GH_EMAIL（你的邮箱地址）和 GH_NAME（你的 GitHub 用户名）。
5. 在你的仓库根目录下创建一个 .travis.yml 文件，内容如下：

.travis.yml

language: node_js
node_js:
  - 18
branches:
  only:
    - main
cache:
  yarn: true
script:
  - git config --global user.name "${GH_NAME}"
  - git config --global user.email "${GH_EMAIL}"
  - echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
  - yarn install
  - GIT_USER="${GH_NAME}" yarn deploy

现在，每当有新的提交合并到 main 分支时，Travis CI 就会运行你的测试套件，如果一切通过，你的网站将通过 yarn deploy 脚本进行部署。

使用 Buddy 触发部署

Buddy 是一个易于使用的 CI/CD 工具，它允许你将你的门户自动化部署到不同的环境，包括 GitHub Pages。

按照以下步骤创建一个 pipeline，以便在你每次向所选的项目分支推送更改时，自动部署新版本的网站：

1. 前往 https://github.com/settings/tokens 并生成一个新的个人访问令牌。在创建令牌时，授予它 repo 范围，以便它拥有所需的权限。
2. 登录到你的 Buddy 账户并创建一个新项目。
3. 选择 GitHub 作为你的 git 托管提供商，并选择包含你网站代码的仓库。
4. 使用左侧导航面板，切换到 Pipelines 视图。
5. 创建一个新的 pipeline。定义它的名称，将触发模式设置为 On push，并选择触发 pipeline 执行的分支。
6. 添加一个 Node.js 操作。
7. 在该操作的终端中添加以下命令：

GIT_USER=<GH_PERSONAL_ACCESS_TOKEN>
git config --global user.email "<YOUR_GH_EMAIL>"
git config --global user.name "<YOUR_GH_USERNAME>"
yarn deploy

创建这个简单的 pipeline 后，每次推送到你所选分支的新提交都会使用 yarn deploy 将你的网站部署到 GitHub Pages。阅读本指南以了解更多关于为 道格龙（Docusaurus）设置 CI/CD pipeline 的信息。

使用 Azure Pipelines

1. 如果你还没有账户，请在 Azure Pipelines 注册。
2. 创建一个组织。在组织内，创建一个项目并从 GitHub 连接你的仓库。
3. 前往 https://github.com/settings/tokens 并生成一个具有 repo 范围的新的个人访问令牌。
4. 在项目页面（URL 类似于 https://dev.azure.com/ORG_NAME/REPO_NAME/_build），使用以下文本创建一个新的 pipeline。同时，点击编辑并添加一个名为 GH_TOKEN 的新环境变量，其值为你新生成的令牌，然后再添加 GH_EMAIL（你的邮箱地址）和 GH_NAME（你的 GitHub 用户名）。请确保将它们标记为机密。或者，你也可以在你的仓库根目录添加一个名为 azure-pipelines.yml 的文件。

azure-pipelines.yml

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    persistCredentials: true

  - task: NodeTool@0
    inputs:
      versionSpec: '18'
    displayName: 安装 Node.js

  - script: |
      git config --global user.name "${GH_NAME}"
      git config --global user.email "${GH_EMAIL}"
      git checkout -b main
      echo "machine github.com login ${GH_NAME} password ${GH_TOKEN}" > ~/.netrc
      yarn install
      GIT_USER="${GH_NAME}" yarn deploy
    env:
      GH_NAME: $(GH_NAME)
      GH_EMAIL: $(GH_EMAIL)
      GH_TOKEN: $(GH_TOKEN)
    displayName: 安装并构建

使用 Drone

1. 创建一个新的 SSH 密钥，它将作为你项目的部署密钥。
2. 为你的私钥和公钥命名，使其具有特异性，并且不会覆盖你其他的 SSH 密钥。
3. 前往 https://github.com/USERNAME/REPO/settings/keys 并通过粘贴你刚刚生成的公钥来添加一个新的部署密钥。
4. 打开你的 Drone.io 仪表板并登录。URL 看起来像 https://cloud.drone.io/USERNAME/REPO。
5. 点击仓库，点击激活仓库，并添加一个名为 git_deploy_private_key 的 secret，其值为你刚刚生成的私钥。
6. 在你的仓库根目录下创建一个 .drone.yml 文件，内容如下。

.drone.yml

kind: pipeline
type: docker
trigger:
  event:
    - tag
- name: Website
  image: node
  commands:
    - mkdir -p $HOME/.ssh
    - ssh-keyscan -t rsa github.com >> $HOME/.ssh/known_hosts
    - echo "$GITHUB_PRIVATE_KEY" > "$HOME/.ssh/id_rsa"
    - chmod 0600 $HOME/.ssh/id_rsa
    - cd website
    - yarn install
    - yarn deploy
  environment:
    USE_SSH: true
    GITHUB_PRIVATE_KEY:
      from_secret: git_deploy_private_key

现在，每当您将新标签推送到 GitHub 时，这个触发器将启动 Drone CI 来发布您的网站。

部署到 Flightcontrol

Flightcontrol 是一项服务，可直接从你的 Git 仓库自动构建 Web 应用并将其部署到 AWS Fargate。它让你拥有完全的访问权限来检查和进行基础设施更改，而不受传统 PaaS 的限制。

按照 Flightcontrol 的 Docusaurus 分步指南开始使用。

部署到 Koyeb

Koyeb 是一个对开发者友好的无服务器平台，用于在全球范围内部署应用。该平台让你能够无缝运行 Docker 容器、Web 应用和 API，并提供基于 Git 的部署、原生自动扩缩、全球边缘网络以及内置的服务网格和发现功能。查看 Koyeb 的 Docusaurus 部署指南以开始使用。

部署到 Render

Render 提供免费的静态网站托管，包括完全托管的 SSL、自定义域名、全球 CDN，以及从你的 Git 仓库持续自动部署。按照 Render 的 Docusaurus 部署指南，只需几分钟即可开始。

部署到 Qovery

Qovery 是一个完全托管的云平台，运行在你的 AWS、Digital Ocean 和 Scaleway 账户上，你可以在一个地方托管静态网站、后端 API、数据库、定时任务以及所有其他应用。

1. 创建一个 Qovery 账户。如果你还没有账户，请访问 Qovery 仪表板进行创建。
2. 创建一个项目。
   • 点击 Create project 并为你的项目命名。
   • 点击 Next。
3. 创建一个新环境。
   • 点击 Create environment 并命名（例如 staging、production）。
4. 添加一个应用。
   • 点击 Create an application，命名并选择你的 Docusaurus 应用所在的 GitHub 或 GitLab 仓库。
   • 定义主分支名称和根应用路径。
   • 点击 Create。应用创建后：
   • 导航到你的应用 Settings
   • 选择 Port
   • 添加你的 Docusaurus 应用使用的端口
5. 部署
   • 现在你所要做的就是导航到你的应用并点击 Deploy。

就是这样。观察状态，等待应用部署完成。要在浏览器中打开应用，请在你的应用概览中点击 Action 和 Open。

部署到 Hostman

Hostman 允许你免费托管静态网站。Hostman 会自动化一切流程，你只需连接你的仓库并按照以下简单步骤操作：

1. 创建一个服务。

   • 要部署 Docusaurus 静态网站，请点击你仪表板左上角的 Create，然后选择 Front-end app or static website。

2. 选择要部署的项目。

   • 如果你使用 GitHub、GitLab 或 Bitbucket 账户登录 Hostman，你将看到包含你的项目（包括私有项目）的仓库。

   • 选择你想要部署的项目。它必须包含项目文件的目录（例如 website）。

   • 要访问不同的仓库，请点击 Connect another repository。

   • 如果你没有使用 Git 账户凭据登录，你现在可以访问必要的账户，然后选择项目。

3. 配置构建设置。

   • 接下来，将出现 Website customization 窗口。从框架列表中选择 Static website 选项。

   • Directory with app 指向构建后将包含项目文件的目录。如果你在第 2 步中选择了包含网站（或 my_website）目录内容的仓库，则可以将其留空。

   • Docusaurus 的标准构建命令是：

     npm

     npm run build

     Yarn

     yarn build

     pnpm

     pnpm run build

     Bun

     bun run build

   • 如果需要，你可以修改构建命令。你可以输入多个由 && 分隔的命令。

4. 部署。

   • 点击 Deploy 开始构建过程。

   • 一旦开始，你将进入部署日志。如果代码有任何问题，你将在日志中看到警告或错误消息，指出问题的原因。通常，日志包含你需要的所有调试数据。

   • 部署完成后，你将收到一封电子邮件通知，并看到一条日志条目。一切完成！你的项目已启动并准备就绪。

部署到 Surge

Surge 是一个静态 Web 托管平台，你可以在几秒钟内从命令行部署你的 Docusaurus 项目。将你的项目部署到 Surge 既简单又免费（包括自定义域名和 SSL 证书）。

通过以下步骤在几秒钟内部署你的应用：

1. 首先，使用 npm 安装 Surge，运行以下命令：
   npm

   npm install -g surge

   Yarn

   yarn global add surge

   pnpm

   pnpm add -g surge

   Bun

   bun add --global surge

2. 要在你的项目根目录中为生产环境构建站点的静态文件，请运行：
   npm

   npm run build

   Yarn

   yarn build

   pnpm

   pnpm run build

   Bun

   bun run build

3. 然后，在你的项目根目录内运行此命令：

   surge build/

首次使用 Surge 的用户将被提示从命令行创建一个账户（只需要执行一次）。

确认你想要发布的网站位于 build 目录中。系统会总是提供一个随机生成的子域名 *.surge.sh（可以编辑）。

使用你的域名

如果你有域名，你可以使用以下命令部署你的网站：

surge build/ your-domain.com

你的网站现在免费部署在 subdomain.surge.sh 或 your-domain.com，具体取决于你选择的方法。

设置 CNAME 文件

使用以下命令将你的域名存储在 CNAME 文件中以备将来部署：

echo subdomain.surge.sh > CNAME

将来你可以使用 surge 命令部署任何其他更改。

部署到 Stormkit

你可以将你的 Docusaurus 项目部署到 Stormkit，这是一个用于静态网站、单页应用（SPA）和无服务器功能的部署平台。有关详细说明，请参阅本指南。

部署到 QuantCDN

1. 安装 Quant CLI
2. 通过注册创建一个 QuantCDN 账户
3. 使用 quant init 初始化你的项目并填写你的凭据：

   quant init

4. 部署你的网站。

   quant deploy

有关部署到 QuantCDN 的更多示例和用例，请参阅文档和博客。

部署到 Cloudflare Pages

Cloudflare Pages 是一个供前端开发者协作和部署网站的 Jamstack 平台。按照此页面的说明，在几分钟内即可开始。

部署到 Azure Static Web Apps

Azure Static Web Apps 是一项直接从代码仓库自动构建和部署全栈 Web 应用到 Azure 的服务，简化了开发者的 CI/CD 体验。Static Web Apps 将 Web 应用的静态资产与其动态（API）端点分开。静态资产从全球分布的内容服务器提供，使客户端能够使用附近的服务器更快地检索文件。动态 API 使用无服务器架构进行扩展，采用事件驱动的基于函数的方法，更具成本效益并可按需扩展。按照此分步指南，在几分钟内即可开始。

部署到 Kinsta

通过 Kinsta 静态网站托管，你可以免费部署多达 100 个静态网站，并享有自定义域名、SSL、每月 100 GB 带宽以及超过 260 个 Cloudflare CDN 节点的服务。

按照我们的《Docusaurus on Kinsta》文章，只需点击几下即可开始。