部署

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

npm run build

yarn build

pnpm run build

完成后，静态文件将在build目录中生成。

您可以将您的站点部署到静态站点托管服务，例如 Vercel, GitHub Pages, Netlify, Render, 和 Surge.

Docusaurus 网站是静态渲染的，通常可以在没有 JavaScript 的情况下工作！

配置​

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

本地测试你的构建​

在部署到生产环境之前，本地测试您的构建非常重要。Docusaurus 提供了一个 docusaurus serve 命令来实现这一点：

npm run serve

yarn serve

pnpm run serve

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

尾部斜杠配置​

Docusaurus 有一个 trailingSlash 配置，允许自定义 URL/链接和生成的文件名模式。

默认值通常工作良好。不幸的是，每个静态托管提供商都有不同的行为，将完全相同的站点部署到不同的主机可能会导致不同的结果。根据您的主机，更改此配置可能是有用的。

使用环境变量​

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

// If you are using dotenv (https://www.npmjs.com/package/dotenv)
import 'dotenv/config';

export default {
  title: '...',
  url: process.env.URL, // You can use environment variables to control site specifics as well
  customFields: {
    // Put your custom environment here
    teamEmail: process.env.EMAIL,
  },
};

import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

export default function Home() {
  const {
    siteConfig: {customFields},
  } = useDocusaurusContext();
  return <div>Contact us through {customFields.teamEmail}!</div>;
}

选择托管服务提供商​

有几种常见的托管选项：

• 自托管 使用像 Apache2 或 Nginx 这样的 HTTP 服务器。
• Jamstack 提供商（例如 Netlify 和 Vercel）。我们将以它们为参考，但同样的推理也适用于其他提供商。
• GitHub Pages（根据定义，它也是Jamstack，但我们单独进行比较）。

如果你不确定选择哪一个，可以问以下问题：

没有银弹。在做出选择之前，你需要权衡你的需求和资源。

自托管​

Docusaurus 可以使用 docusaurus serve 进行自托管。使用 --port 更改端口，使用 --host 更改主机。

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

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

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

部署到 Netlify​

要将您的Docusaurus站点部署到Netlify，首先请确保以下选项已正确配置：

export default {
  url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
  baseUrl: '/', // Base directory of your site relative to your repo
  // ...
};

然后，使用Netlify创建您的站点。

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

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

如果您没有配置这些构建选项，您仍然可以在站点创建后前往“站点设置” -> “构建与部署”。

一旦正确配置了上述选项，您的站点应该会在合并到您的部署分支（默认为main）时自动部署和重新部署。

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

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

部署到 Vercel​

将您的Docusaurus项目部署到Vercel将为您提供各种好处，包括性能和易用性方面的优势。

要使用Vercel for Git Integration部署您的Docusaurus项目，请确保它已被推送到Git仓库。

使用导入流程将项目导入Vercel。在导入过程中，您会发现所有相关选项都已为您预先配置；但是，您可以选择更改这些选项中的任何一个。

在您的项目被导入后，所有后续推送到分支的操作都会生成预览部署，并且所有对生产分支（通常是“main”或“master”）的更改都会导致生产部署。

部署到GitHub Pages​

Docusaurus 提供了一种简单的方法来发布到 GitHub Pages，每个 GitHub 仓库都免费提供此服务。

概述​

通常，发布过程中会涉及两个仓库（至少两个分支）：包含源文件的分支，以及包含要通过GitHub Pages提供的构建输出的分支。在以下教程中，它们将分别被称为"source"和"deployment"。

每个 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 从默认分支（通常是 master / main）或 gh-pages 分支中获取可部署的文件（docusaurus build 的输出），这些文件可以来自根目录或 /docs 文件夹。你可以通过仓库中的 Settings > Pages 进行配置。这个分支将被称为“部署分支”。

我们提供了一个docusaurus deploy命令，帮助您通过一个命令从源分支部署站点到部署分支：克隆、构建和提交。

docusaurus.config.js 设置​

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

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

示例：

export default {
  // ...
  url: 'https://endiliey.github.io', // Your website URL
  baseUrl: '/',
  projectName: 'endiliey.github.io',
  organizationName: 'endiliey',
  trailingSlash: false,
  // ...
};

环境设置​

GitHub 企业版安装应与 github.com 相同；您只需将组织的 GitHub Enterprise 主机设置为环境变量：

部署​

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

GIT_USER=<GITHUB_USERNAME> yarn deploy

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

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

使用 GitHub Actions 触发部署​

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

以下工作流示例假设您的网站源代码位于存储库的main分支中（源分支为main），并且您的发布源已配置为使用自定义GitHub Actions工作流发布。

我们的目标是：

1. 当向main提交新的拉取请求时，有一个操作确保站点成功构建，而无需实际部署。此任务将被称为test-deploy。
2. 当拉取请求合并到main分支或有人直接推送到main分支时，它将构建并部署到GitHub Pages。此作业将被称为deploy。

以下是使用GitHub Actions部署文档的两种方法。根据您的部署仓库的位置，选择下面的相关选项卡：

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

name: 部署到 GitHub Pages

on:
  push:
    branches:
      - main
    # 如果你想进一步定义触发器、路径等，请查看 GitHub 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:
<span class="token-line" style

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:
<span class="token-line" style="color:#

使用 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，并导航到您仓库的更多选项 > 设置 > 环境变量部分。
4. 创建一个名为GH_TOKEN的新环境变量，其值为新生成的令牌，然后是GH_EMAIL（您的电子邮件地址）和GH_NAME（您的GitHub用户名）。
5. 在您的仓库根目录下创建一个.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。

按照以下步骤创建一个管道，每当您将更改推送到项目的选定分支时，该管道会自动部署新版本的网站：

1. 前往 https://github.com/settings/tokens 并生成一个新的 个人访问令牌。创建令牌时，授予它 repo 范围，以便它拥有所需的权限。
2. 登录您的Buddy账户并创建一个新项目。
3. 选择 GitHub 作为您的 git 托管提供商，并选择包含您网站代码的存储库。
4. 使用左侧导航面板，切换到Pipelines视图。
5. 创建一个新的流水线。定义其名称，将触发模式设置为On push，并选择触发流水线执行的分支。
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

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

使用 Azure Pipelines​

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

trigger:
  - main

pool:
  vmImage: ubuntu-latest

steps:
  - checkout: self
    persistCredentials: true

  - task: NodeTool@0
    inputs:
      versionSpec: '18'
    displayName: Install 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: Install and build

使用无人机​

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的密钥，其值为你刚刚生成的私钥。
6. 在您的仓库根目录下创建一个.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. 创建一个项目。
   • 点击创建项目并为您的项目命名。
   • 点击下一步。
3. 创建一个新环境。
   • 点击创建环境并为其命名（例如：staging, production）。
4. 添加一个应用程序。
   • 点击创建应用程序，命名并选择您的GitHub或GitLab仓库，其中包含您的Docusaurus应用程序。
   • 定义主分支名称和根应用程序路径。
   • 点击创建。应用程序创建后：
   • 导航到您的应用程序设置
   • 选择端口
   • 添加您的Docusaurus应用程序使用的端口
5. 部署
   • 你现在需要做的就是导航到你的应用程序并点击部署。

就这样。观察状态并等待应用程序部署完成。要在浏览器中打开应用程序，请在应用程序概览中点击操作和打开。

部署到 Hostman​

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

1. 创建一个服务。

   • To deploy a Docusaurus static website, click Create in the top-left corner of your Dashboard and choose Front-end app or static website.

2. 选择要部署的项目。

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

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

   • 要访问不同的仓库，请点击连接另一个仓库。

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

3. 配置构建设置。

   • 接下来，将出现网站定制窗口。从框架列表中选择静态网站选项。

   • 包含应用程序的目录指向构建后将包含项目文件的目录。如果您在步骤2中选择了包含网站内容（或my_website）目录的存储库，您可以将其留空。

   • Docusaurus 的标准构建命令是：

     • npm
     • Yarn
     • pnpm

     npm run build
     

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

4. 部署。

   • 点击部署以开始构建过程。

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

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

部署到Surge​

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

使用Surge在几秒钟内部署您的应用程序，步骤如下：

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

   npm install -g surge
   
2. 要在项目的根目录中为生产环境构建站点的静态文件，请运行：
   • npm
   • Yarn
   • pnpm

   npm run build
   
3. 然后，在项目的根目录中运行以下命令：

   surge build/
   

首次使用Surge的用户将会被提示从命令行创建一个账户（这只会发生一次）。

确认您要发布的站点位于build目录中。系统会始终提供一个随机生成的子域名*.surge.sh subdomain（可以编辑）。

使用您的域名​

如果您有一个域名，您可以使用以下命令部署您的站点：

surge build/ your-domain.com

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

设置CNAME文件​

将您的域名存储在CNAME文件中，以便将来使用以下命令进行部署：

echo subdomain.surge.sh > CNAME

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

部署到Stormkit​

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

部署到 QuantCDN​

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

   quant init
   
4. 部署你的站点。

   quant deploy
   

请参阅文档和博客以获取更多关于部署到QuantCDN的示例和用例。

部署到Layer0​

Layer0 是一个一体化平台，用于开发、部署、预览、实验、监控和运行您的无头前端。它专注于大型动态网站，并通过EdgeJS（基于JavaScript的内容分发网络）、预测性预取和性能监控提供一流的性能。Layer0 提供免费层级。只需几分钟即可开始，按照Layer0的Docusaurus部署指南进行操作。

部署到 Cloudflare Pages​

Cloudflare Pages 是一个面向前端开发者的 Jamstack 平台，用于协作和部署网站。通过遵循 这篇文章，您可以在几分钟内开始使用。

部署到 Azure 静态 Web 应用​

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

部署到Kinsta​

Kinsta Static Site Hosting 允许您免费部署多达100个静态站点，支持自定义域名和SSL，每月100 GB的带宽，以及260多个Cloudflare CDN位置。

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