进阶 docusaurus.io 2026-10-13 10:58:59 · 23 阅读
第7章 Docusaurus 部署指南
版本：2.x部署
要构建网站的生产环境静态文件，请执行：
npmYarnpnpmBunnpm run build
yarn build
pnpm run build
bun run build
完成后，静态文件将生成在 build 目录下。 noteDocusaurus 的唯一职责是构建你的网站并输出 build 目录中的静态文件。接下来如何托管这些静态文件由你决定。 你可以将站点部署到静态站点托管服务，如 Vercel、GitHub Pages、Netlify、Render、Surge 等。 Docusaurus 站点是静态渲染的，通常无需 JavaScript 即可正常工作！ 配置 在 docusaurus.config.js 中，以下参数对于优化路由和从正确位置提供文件是必需的： NameDescriptionurl你站点的 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 命令用于此目的： npmYarnpnpmBunnpm run serve
yarn serve
pnpm run serve
bun run serve
默认情况下，这会在 http://localhost:3000/ 加载你的站点。 尾斜杠配置 Docusaurus 有一个 trailingSlash 配置项，允许自定义 URL/链接以及输出的文件名模式。 默认值通常适用。不幸的是，每个静态托管提供商的行为各不相同，将完全相同的站点部署到不同的托管商可能导致不同的结果。根据你的托管商，修改此配置可能很有用。 tip使用 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)
require('dotenv').config();
module.exports = {
title: '...',
url: process.env.URL, // 也可以用环境变量来控制站点的相关配置
customFields: {
// 在这里放置你的自定义环境变量
teamEmail: process.env.EMAIL,
},
};
home.jsximport useDocusaurusContext from '@docusaurus/useDocusaurusContext';
export default function Home() {
const {
siteConfig: {customFields},
} = useDocusaurusContext();
return
} 选择托管提供商 常见的托管方案有几种： 自建 HTTP 服务器托管，例如 Apache2 或 Nginx； Jamstack 提供商，例如 Netlify 和 Vercel。我们将以它们为参考，同样的逻辑也适用于其他提供商。 GitHub Pages。（按定义，它也属于 Jamstack，但我们单独对比。） 如果不确定该选哪种，可以问自己以下问题： 我愿意在这上面投入多少资源（人力、金钱）？ 🔴 自建托管最难配置——通常需要有经验的人来管理。云服务几乎很少是免费的，且搭建本地服务器并接入广域网的成本可能更高。 🟢 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 更改主机。 npmYarnpnpmBunnpm 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
bun run serve --build --port 80 --host 0.0.0.0
warning 与使用静态托管服务商或 CDN 相比，这并非最优选择。 warning 接下来，我们将介绍几家常见的托管服务商，以及如何配置它们以最高效地部署 Docusaurus 站点。部分文档由外部贡献者提供。Docusaurus 与上述服务均无利益关联。文档可能未同步最新变更，服务商 API 的近期更新未必反映在我们的文档中。如发现过时内容，欢迎提交 PR。出于类似的时效性考量，我们不再接受新增托管选项的 PR。你可以将你的教程发布在其他网站上（如你的博客或服务商官网），然后联系我们添加链接。 部署到 Netlify 要将 Docusaurus 2 站点部署到 Netlify，请首先确保以下配置正确： docusaurus.config.jsmodule.exports = {
url: 'https://docusaurus-2.netlify.app', // 站点 URL，末尾无需斜杠
baseUrl: '/', // 站点相对于仓库根目录的路径
// ...
};
然后，在 Netlify 上创建你的站点。 设置站点时，请按如下指定构建命令和目录： 构建命令: npm run build 发布目录: build 如果未设置这些构建选项，站点创建后也可前往“站点设置”->“构建与部署”进行配置。 配置完成后，站点应在合并到部署分支（默认 main）时自动部署并重新部署。 warning 部分 Docusaurus 站点将 docs 文件夹放在 website 目录之外（常见于 Docusaurus v1 站点）：repo # git 根目录
├── docs # MD 文件
└── website # Docusaurus 根目录
如果你决定使用 website 文件夹作为 Netlify 的基础目录，更新 docs 文件夹时将不会触发构建，需要配置自定义的忽略命令：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 的 Git 集成部署 Docusaurus 项目，先把项目推送到 Git 仓库。 然后使用 Import Flow 将项目导入 Vercel。导入过程中所有相关选项都已为你预先配置好，当然你也可以自行修改，可配置项列表见这里。 项目导入后，之后推送到任何分支都会生成预览部署（Preview Deployment），而推送到生产分支（通常是 main 或 master）的改动则会触发生产环境部署。 部署到 GitHub Pages Docusaurus 提供了便捷的方式发布到 GitHub Pages，而 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 绑定自定义域名，需要在 static 目录下创建一个 CNAME 文件。static 目录中的所有内容都会被复制到构建目录的根目录下用于部署。使用自定义域名时，你可以把 baseUrl: '/projectName/' 改回 baseUrl: '/'，并把 url 设置为你的自定义域名。 详情可参考 GitHub Pages 官方文档 User, Organization, and Project Pages。 GitHub Pages 会从默认分支（通常是 master / main）或 gh-pages 分支中读取可部署文件（即 docusaurus build 的输出），位置可以是根目录或 /docs 文件夹。你可以在仓库的 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，不要留空）。 示例： docusaurus.config.jsmodule.exports = {
// ...
url: 'https://endiliey.github.io', // 你的网站 URL
baseUrl: '/',
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// ...
};
警告：默认情况下，GitHub Pages 会使用 Jekyll 处理发布的文件。由于 Jekyll 会丢弃所有以 _ 开头的文件，建议在静态目录中添加一个名为 .nojekyll 的空文件来禁用 Jekyll。 环境配置 名称描述USE_SSH设置为 true 时，使用 SSH 替代默认的 HTTPS 连接 GitHub 仓库。如果源仓库 URL 是 SSH URL（例如 [email protected]:facebook/docusaurus.git），则自动推断 USE_SSH 为 true。GIT_USER拥有部署仓库推送权限的 GitHub 账号用户名。对于自己的仓库，通常就是你的 GitHub 用户名。若未使用 SSH 则必填，使用 SSH 则忽略此变量。GIT_PASSGIT_USER 对应的个人访问令牌，用于支持非交互式部署（例如持续部署）。CURRENT_BRANCH源分支。通常是 main 或 master，也可以是除 gh-pages 外的任意分支。若未设置此变量，则使用执行 docusaurus deploy 命令时所在的当前分支。 GitHub Enterprise 环境的安装方式与 github.com 类似，只需将组织的 GitHub Enterprise 主机设置为环境变量即可： 名称描述GITHUB_HOST你的 GitHub Enterprise 站点域名。GITHUB_PORT你的 GitHub Enterprise 站点端口。 部署 最后，将你的网站部署到 GitHub Pages，请运行： BashWindowsPowerShellGIT_USER= yarn deploy
cmd /C "set "GIT_USER=" && yarn deploy"
cmd /C 'set "GIT_USER=" && yarn deploy'
warning2021 年 8 月起，GitHub 要求所有命令行登录必须使用个人访问令牌（PAT）而非密码。当 GitHub 提示输入密码时，请输入 PAT。更多详情请参阅 GitHub 文档。另一种方式是使用 SSH（设置 `USE_SSH=true`）进行登录。 通过 GitHub Actions 触发部署 GitHub Actions 允许你在代码仓库中自动化、定制并执行软件开发工作流。 以下工作流示例假设你的网站源码位于仓库的 main 分支（源码分支为 main），且发布源配置为 gh-pages 分支（部署分支为 gh-pages）。 我们的目标是实现： 当向 main 分支发起新的 Pull Request 时，触发一个动作以确保网站构建成功，但不实际执行部署。该任务命名为 test-deploy。 当 Pull Request 合并至 main 分支，或有人直接向 main 分支推送代码时，网站将被构建并部署到 gh-pages 分支。随后，新的构建产物将通过 GitHub Pages 站点提供服务。该任务命名为 deploy。 以下是使用 GitHub Actions 部署文档的两种方法。请根据你的部署分支（gh-pages）的位置，选择下方对应的选项卡： 源码仓库和部署仓库是同一个仓库。 部署仓库是一个远程仓库，与源码仓库不同。 相同远程虽然你可以在同一个 workflow 文件中定义这两个任务，但原始 deploy workflow 在 PR 检查套件状态中始终显示为“跳过（skipped）”，这既不能反映实际状态，也无助于评审过程。因此，我们建议将它们作为独立的 workflow 进行管理。我们将使用一个流行的第三方部署 action：peaceiris/actions-gh-pages。GitHub action 文件添加这两个 workflow 文件：针对你的配置调整参数这些文件假设你正在使用 Yarn。如果你使用 npm，请将 `cache: yarn`、`yarn install --frozen-lockfile`、`yarn build` 分别更改为 `cache: npm`、`npm ci`、`npm run build`。如果你的 Docusaurus 项目不在仓库根目录，可能需要配置默认工作目录，并相应调整路径。.github/workflows/deploy.ymlname: Deploy to GitHub Pages
on:
push:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
permissions:
contents: write
jobs:
deploy:
name: 部署到 GitHub Pages
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn
- name: 安装依赖
run: yarn install --frozen-lockfile
- name: 构建网站
run: yarn build
# 部署到 GitHub Pages 的常用 action：
# 文档：https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
- name: 部署到 GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
# 要发布到 `gh-pages` 分支的构建产物目录：
publish_dir: ./build
# 下面两行把提交作者设置为官方的
# GH-Actions 机器人，用于向 `gh-pages` 分支部署：
# https://github.com/actions/checkout/issues/13#issuecomment-724415212
# 如果不指定这两个字段，默认会使用 GH actions 机器人。
# 你也可以换成自己的用户凭据。
user_name: github-actions[bot]
user_email: 41898282+github-actions[bot]@users.noreply.github.com
.github/workflows/test-deploy.ymlname: 测试部署
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@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn
- name: 安装依赖
run: yarn install --frozen-lockfile
- name: 测试构建网站
run: yarn build
跨仓库发布配置较为复杂，因为你需要向另一个仓库推送内容并进行权限验证。我们将使用 SSH 进行身份验证。 生成一个新的 SSH 密钥。由于该密钥将在 CI 中使用，请确保不设置任何密码短语。 默认情况下，你的公钥应保存在 ~/.ssh/id_rsa.pub；否则，请使用上一步中提供的文件名，将你的密钥添加到 GitHub 部署密钥（deploy keys）中。 使用 pbcopy < ~/.ssh/id_rsa.pub 将密钥复制到剪贴板，然后将其粘贴到目标部署仓库的部署密钥设置中。如果命令行不起作用，可直接复制文件内容。保存部署密钥前，务必勾选“允许写入访问”（Allow write access）选项。 你需要将私钥作为 GitHub 机密（secret）设置，以便 Docusaurus 替你执行部署操作。 使用 pbcopy < ~/.ssh/id_rsa 复制私钥，然后在源仓库创建一个名为 GH_PAGES_DEPLOY 的 GitHub 机密并粘贴内容。如果命令行不起作用，可直接复制文件内容。保存该机密。 在 .github/workflows/ 目录下创建你的文档工作流。本例中使用的是 deploy.yml 文件。 你应准备好：源仓库中设置包含私有 SSH 密钥作为 GitHub 机密的 GitHub 工作流，以及部署仓库中设置包含公有 SSH 密钥的 GitHub 部署密钥。 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.ymlname: Deploy to 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@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build
deploy:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
`
`git config --global user.email ""`
`git config --global user.name ""`
`yarn deploy`
配置好这条简单流水线后，每次向所选分支推送新提交时，系统便会执行 `yarn deploy`，将网站部署到 GitHub Pages。如需了解如何为 Docusaurus 搭建 CI/CD 流水线，请参阅此指南。
使用 Azure Pipelines
如果尚未注册，请先在 Azure Pipelines 上创建账户。
创建一个组织。在组织内新建项目，并将 GitHub 上的仓库连接至该项目。
访问 https://github.com/settings/tokens，生成一个具有 repo 权限的新个人访问令牌。
在项目页面（类似 https://dev.azure.com/ORG_NAME/REPO_NAME/_build）中，使用以下文本创建新流水线。同时，点击编辑按钮，新增名为 GH_TOKEN 的环境变量并填入刚生成的令牌值，再添加 GH_EMAIL（你的邮箱）和 GH_NAME（你的 GitHub 用户名）。务必将这些变量标记为 secret（机密）。或者，你也可以在仓库根目录添加名为 azure-pipelines.yml 的文件。
azure-pipelines.ymltrigger:
- 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
使用 Drone 创建一个新的 SSH 密钥作为项目的部署密钥。 为私钥和公钥命名时要具体明确，避免覆盖已有的其他 SSH 密钥。 访问 https://github.com/USERNAME/REPO/settings/keys，粘贴刚生成的公钥来添加一个新的部署密钥。 打开 Drone.io 仪表盘并登录。URL 格式类似 https://cloud.drone.io/USERNAME/REPO。 点击目标仓库，选择“activate repository”（激活仓库），并添加名为 git_deploy_private_key 的 secret（机密），值为你刚生成的私钥内容。 在仓库根目录创建 .drone.yml 文件，内容如下。 .drone.ymlkind: 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 任务以发布你的网站。 部署到 Koyeb Koyeb 是一个面向开发者的 Serverless 平台，支持全球应用部署。它允许你无缝运行 Docker 容器、Web 应用和 API，并提供基于 Git 的部署、原生自动扩缩容、全球边缘网络以及内置的服务网格与发现功能。你可以参考 Koyeb 的 Docusaurus 部署指南快速上手。 部署到 Render Render 提供免费的静态站点托管，包含全托管 SSL、自定义域名、全球 CDN 以及从 Git 仓库进行的持续自动部署。跟随 Render 部署 Docusaurus 的指南，只需几分钟即可完成配置。 部署到 Qovery Qovery 是一个全托管云平台，运行在你的 AWS、Digital Ocean 或 Scaleway 账户上，让你可以在一个地方托管静态站点、后端 API、数据库、定时任务以及其他所有应用。 创建一个 Qovery 账户。如果你还没有账户，请访问 Qovery 仪表盘创建。 创建一个项目。 点击 Create project 并为项目命名。 点击 Next。 创建新环境。 点击 Create environment 并命名环境（例如 staging、production）。 添加应用。 点击 Create an application，输入名称，并选择存放 Docusaurus 应用的 GitHub 或 GitLab 仓库。 定义主分支名称和根应用路径。 点击 Create。应用创建完成后： 导航至应用 Settings 选择 Port 添加 Docusaurus 应用使用的端口 一键部署 现在只需导航到应用页面并点击 Deploy。 就这样。监控状态直至应用部署完成。要在浏览器中打开应用，请在应用概览中点击 Action 并选择 Open。 部署到 Hostman Hostman 允许你免费托管静态网站。它实现了全流程自动化，你只需连接仓库并跟随简单步骤即可： 创建服务。 要部署 Docusaurus 静态网站，请在仪表盘左上角点击 Create，并选择 Front-end app 或 static website。 选择要部署的项目。 如果你使用 GitHub、GitLab 或 Bitbucket 账户登录 Hostman，此时将看到包含私有仓库在内的项目列表。 选择你要部署的项目。该目录必须包含项目文件（例如 website）。 如需访问其他仓库，请点击 Connect another repository。 如果你未使用 Git 账户凭据登录，现在可以访问相应账户并选择项目。 配置构建设置。 接下来会出现 Website customization 窗口。请从框架列表中选择 Static website 选项。 Directory with app 指向构建完成后包含项目文件的目录。如果在第 2 步中选择了包含网站内容（或 my_website）目录的仓库，则此项可以留空。 Docusaurus 的标准构建命令为： npmYarnpnpmBunnpm run build
yarn build
pnpm run build
bun run build
必要时可修改构建命令，支持用 && 分隔多个指令。 部署 点击 Deploy 启动构建流程。开始后即可查看部署日志。若代码存在问题，日志中会显示警告或错误信息并说明原因。通常情况下，日志包含调试所需的全部数据。 部署完成后，你会收到邮件通知及日志记录。至此项目上线完毕，即刻可用。 部署到 Surge Surge 是静态网站托管平台，支持通过命令行在一分钟内部署 Docusaurus 项目。操作简单且免费（含自定义域名及 SSL）。 按以下步骤使用 Surge 在数秒内完成部署： 首先，运行以下命令通过 npm 安装 Surge： npmYarnpnpmBunnpm install -g surge
yarn global add surge
pnpm add -g surge
bun add --global surge
在项目根目录下运行以下命令以生成生产环境静态文件： npmYarnpnpmBunnpm run build
yarn build
pnpm run build
bun run build
然后在项目根目录下运行： 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 命令即可部署其他变更。 部署到 QuantCDN 安装 Quant CLI 注册 QuantCDN 账户 运行 quant init 初始化项目并填入凭据： quant init
部署站点。 quant deploy
更多部署到 QuantCDN 的示例和用例，请参阅文档和博客。 部署到 Layer0 Layer0 是一个一体化平台，可用于开发、部署、预览、实验、监控和运行无头前端。它专注于大型动态网站，通过 EdgeJS（基于 JavaScript 的 CDN）、预测性预取和性能监控实现一流的性能。Layer0 提供免费套餐，按照 Layer0 的 Docusaurus 部署指南操作，几分钟即可上手。 部署到 Cloudflare Pages Cloudflare Pages 是一个面向前端开发者的 Jamstack 平台，支持协作和网站部署。按照这篇文章操作，几分钟即可上手。 部署到 Azure Static Web Apps Azure Static Web Apps 是一项服务，可以直接从代码仓库自动构建全栈 Web 应用并部署到 Azure，简化 CI/CD 的开发体验。它将 Web 应用的静态资源与动态（API）端点分开：静态资源由全球分布式的内容服务器提供，客户端可以从附近的服务器更快地获取文件；动态 API 则采用事件驱动的 Serverless 函数架构，更具成本效益并按需扩展。按照这份分步指南操作，几分钟即可上手。
yarn build
pnpm run build
bun run build
完成后，静态文件将生成在 build 目录下。 noteDocusaurus 的唯一职责是构建你的网站并输出 build 目录中的静态文件。接下来如何托管这些静态文件由你决定。 你可以将站点部署到静态站点托管服务，如 Vercel、GitHub Pages、Netlify、Render、Surge 等。 Docusaurus 站点是静态渲染的，通常无需 JavaScript 即可正常工作！ 配置 在 docusaurus.config.js 中，以下参数对于优化路由和从正确位置提供文件是必需的： NameDescriptionurl你站点的 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 命令用于此目的： npmYarnpnpmBunnpm run serve
yarn serve
pnpm run serve
bun run serve
默认情况下，这会在 http://localhost:3000/ 加载你的站点。 尾斜杠配置 Docusaurus 有一个 trailingSlash 配置项，允许自定义 URL/链接以及输出的文件名模式。 默认值通常适用。不幸的是，每个静态托管提供商的行为各不相同，将完全相同的站点部署到不同的托管商可能导致不同的结果。根据你的托管商，修改此配置可能很有用。 tip使用 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)
require('dotenv').config();
module.exports = {
title: '...',
url: process.env.URL, // 也可以用环境变量来控制站点的相关配置
customFields: {
// 在这里放置你的自定义环境变量
teamEmail: process.env.EMAIL,
},
};
home.jsximport useDocusaurusContext from '@docusaurus/useDocusaurusContext';
export default function Home() {
const {
siteConfig: {customFields},
} = useDocusaurusContext();
return
通过 {customFields.teamEmail} 联系我们！
;} 选择托管提供商 常见的托管方案有几种： 自建 HTTP 服务器托管，例如 Apache2 或 Nginx； Jamstack 提供商，例如 Netlify 和 Vercel。我们将以它们为参考，同样的逻辑也适用于其他提供商。 GitHub Pages。（按定义，它也属于 Jamstack，但我们单独对比。） 如果不确定该选哪种，可以问自己以下问题： 我愿意在这上面投入多少资源（人力、金钱）？ 🔴 自建托管最难配置——通常需要有经验的人来管理。云服务几乎很少是免费的，且搭建本地服务器并接入广域网的成本可能更高。 🟢 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 更改主机。 npmYarnpnpmBunnpm 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
bun run serve --build --port 80 --host 0.0.0.0
warning 与使用静态托管服务商或 CDN 相比，这并非最优选择。 warning 接下来，我们将介绍几家常见的托管服务商，以及如何配置它们以最高效地部署 Docusaurus 站点。部分文档由外部贡献者提供。Docusaurus 与上述服务均无利益关联。文档可能未同步最新变更，服务商 API 的近期更新未必反映在我们的文档中。如发现过时内容，欢迎提交 PR。出于类似的时效性考量，我们不再接受新增托管选项的 PR。你可以将你的教程发布在其他网站上（如你的博客或服务商官网），然后联系我们添加链接。 部署到 Netlify 要将 Docusaurus 2 站点部署到 Netlify，请首先确保以下配置正确： docusaurus.config.jsmodule.exports = {
url: 'https://docusaurus-2.netlify.app', // 站点 URL，末尾无需斜杠
baseUrl: '/', // 站点相对于仓库根目录的路径
// ...
};
然后，在 Netlify 上创建你的站点。 设置站点时，请按如下指定构建命令和目录： 构建命令: npm run build 发布目录: build 如果未设置这些构建选项，站点创建后也可前往“站点设置”->“构建与部署”进行配置。 配置完成后，站点应在合并到部署分支（默认 main）时自动部署并重新部署。 warning 部分 Docusaurus 站点将 docs 文件夹放在 website 目录之外（常见于 Docusaurus v1 站点）：repo # git 根目录
├── docs # MD 文件
└── website # Docusaurus 根目录
如果你决定使用 website 文件夹作为 Netlify 的基础目录，更新 docs 文件夹时将不会触发构建，需要配置自定义的忽略命令：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 的 Git 集成部署 Docusaurus 项目，先把项目推送到 Git 仓库。 然后使用 Import Flow 将项目导入 Vercel。导入过程中所有相关选项都已为你预先配置好，当然你也可以自行修改，可配置项列表见这里。 项目导入后，之后推送到任何分支都会生成预览部署（Preview Deployment），而推送到生产分支（通常是 main 或 master）的改动则会触发生产环境部署。 部署到 GitHub Pages Docusaurus 提供了便捷的方式发布到 GitHub Pages，而 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 绑定自定义域名，需要在 static 目录下创建一个 CNAME 文件。static 目录中的所有内容都会被复制到构建目录的根目录下用于部署。使用自定义域名时，你可以把 baseUrl: '/projectName/' 改回 baseUrl: '/'，并把 url 设置为你的自定义域名。 详情可参考 GitHub Pages 官方文档 User, Organization, and Project Pages。 GitHub Pages 会从默认分支（通常是 master / main）或 gh-pages 分支中读取可部署文件（即 docusaurus build 的输出），位置可以是根目录或 /docs 文件夹。你可以在仓库的 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，不要留空）。 示例： docusaurus.config.jsmodule.exports = {
// ...
url: 'https://endiliey.github.io', // 你的网站 URL
baseUrl: '/',
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// ...
};
警告：默认情况下，GitHub Pages 会使用 Jekyll 处理发布的文件。由于 Jekyll 会丢弃所有以 _ 开头的文件，建议在静态目录中添加一个名为 .nojekyll 的空文件来禁用 Jekyll。 环境配置 名称描述USE_SSH设置为 true 时，使用 SSH 替代默认的 HTTPS 连接 GitHub 仓库。如果源仓库 URL 是 SSH URL（例如 [email protected]:facebook/docusaurus.git），则自动推断 USE_SSH 为 true。GIT_USER拥有部署仓库推送权限的 GitHub 账号用户名。对于自己的仓库，通常就是你的 GitHub 用户名。若未使用 SSH 则必填，使用 SSH 则忽略此变量。GIT_PASSGIT_USER 对应的个人访问令牌，用于支持非交互式部署（例如持续部署）。CURRENT_BRANCH源分支。通常是 main 或 master，也可以是除 gh-pages 外的任意分支。若未设置此变量，则使用执行 docusaurus deploy 命令时所在的当前分支。 GitHub Enterprise 环境的安装方式与 github.com 类似，只需将组织的 GitHub Enterprise 主机设置为环境变量即可： 名称描述GITHUB_HOST你的 GitHub Enterprise 站点域名。GITHUB_PORT你的 GitHub Enterprise 站点端口。 部署 最后，将你的网站部署到 GitHub Pages，请运行： BashWindowsPowerShellGIT_USER=
cmd /C "set "GIT_USER=
cmd /C 'set "GIT_USER=
warning2021 年 8 月起，GitHub 要求所有命令行登录必须使用个人访问令牌（PAT）而非密码。当 GitHub 提示输入密码时，请输入 PAT。更多详情请参阅 GitHub 文档。另一种方式是使用 SSH（设置 `USE_SSH=true`）进行登录。 通过 GitHub Actions 触发部署 GitHub Actions 允许你在代码仓库中自动化、定制并执行软件开发工作流。 以下工作流示例假设你的网站源码位于仓库的 main 分支（源码分支为 main），且发布源配置为 gh-pages 分支（部署分支为 gh-pages）。 我们的目标是实现： 当向 main 分支发起新的 Pull Request 时，触发一个动作以确保网站构建成功，但不实际执行部署。该任务命名为 test-deploy。 当 Pull Request 合并至 main 分支，或有人直接向 main 分支推送代码时，网站将被构建并部署到 gh-pages 分支。随后，新的构建产物将通过 GitHub Pages 站点提供服务。该任务命名为 deploy。 以下是使用 GitHub Actions 部署文档的两种方法。请根据你的部署分支（gh-pages）的位置，选择下方对应的选项卡： 源码仓库和部署仓库是同一个仓库。 部署仓库是一个远程仓库，与源码仓库不同。 相同远程虽然你可以在同一个 workflow 文件中定义这两个任务，但原始 deploy workflow 在 PR 检查套件状态中始终显示为“跳过（skipped）”，这既不能反映实际状态，也无助于评审过程。因此，我们建议将它们作为独立的 workflow 进行管理。我们将使用一个流行的第三方部署 action：peaceiris/actions-gh-pages。GitHub action 文件添加这两个 workflow 文件：针对你的配置调整参数这些文件假设你正在使用 Yarn。如果你使用 npm，请将 `cache: yarn`、`yarn install --frozen-lockfile`、`yarn build` 分别更改为 `cache: npm`、`npm ci`、`npm run build`。如果你的 Docusaurus 项目不在仓库根目录，可能需要配置默认工作目录，并相应调整路径。.github/workflows/deploy.ymlname: Deploy to GitHub Pages
on:
push:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#on
permissions:
contents: write
jobs:
deploy:
name: 部署到 GitHub Pages
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn
- name: 安装依赖
run: yarn install --frozen-lockfile
- name: 构建网站
run: yarn build
# 部署到 GitHub Pages 的常用 action：
# 文档：https://github.com/peaceiris/actions-gh-pages#%EF%B8%8F-docusaurus
- name: 部署到 GitHub Pages
uses: peaceiris/actions-gh-pages@v3
with:
github_token: ${{ secrets.GITHUB_TOKEN }}
# 要发布到 `gh-pages` 分支的构建产物目录：
publish_dir: ./build
# 下面两行把提交作者设置为官方的
# GH-Actions 机器人，用于向 `gh-pages` 分支部署：
# https://github.com/actions/checkout/issues/13#issuecomment-724415212
# 如果不指定这两个字段，默认会使用 GH actions 机器人。
# 你也可以换成自己的用户凭据。
user_name: github-actions[bot]
user_email: 41898282+github-actions[bot]@users.noreply.github.com
.github/workflows/test-deploy.ymlname: 测试部署
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@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn
- name: 安装依赖
run: yarn install --frozen-lockfile
- name: 测试构建网站
run: yarn build
跨仓库发布配置较为复杂，因为你需要向另一个仓库推送内容并进行权限验证。我们将使用 SSH 进行身份验证。 生成一个新的 SSH 密钥。由于该密钥将在 CI 中使用，请确保不设置任何密码短语。 默认情况下，你的公钥应保存在 ~/.ssh/id_rsa.pub；否则，请使用上一步中提供的文件名，将你的密钥添加到 GitHub 部署密钥（deploy keys）中。 使用 pbcopy < ~/.ssh/id_rsa.pub 将密钥复制到剪贴板，然后将其粘贴到目标部署仓库的部署密钥设置中。如果命令行不起作用，可直接复制文件内容。保存部署密钥前，务必勾选“允许写入访问”（Allow write access）选项。 你需要将私钥作为 GitHub 机密（secret）设置，以便 Docusaurus 替你执行部署操作。 使用 pbcopy < ~/.ssh/id_rsa 复制私钥，然后在源仓库创建一个名为 GH_PAGES_DEPLOY 的 GitHub 机密并粘贴内容。如果命令行不起作用，可直接复制文件内容。保存该机密。 在 .github/workflows/ 目录下创建你的文档工作流。本例中使用的是 deploy.yml 文件。 你应准备好：源仓库中设置包含私有 SSH 密钥作为 GitHub 机密的 GitHub 工作流，以及部署仓库中设置包含公有 SSH 密钥的 GitHub 部署密钥。 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.ymlname: Deploy to 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@v3
- uses: actions/setup-node@v3
with:
node-version: 18
cache: yarn
- name: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build
deploy:
if: github.event_name != 'pull_request'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- uses: webfactory/ssh-agent
with:
ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
- name: Deploy to 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
使用 Travis CI 触发部署
持续集成（CI）服务通常用于在新提交进入版本库时自动执行常规任务，比如运行单元测试和集成测试、自动化构建、将包发布到 npm，以及把变更部署到网站上。要自动化部署你的网站，只需在网站更新时调用 yarn deploy 脚本即可。下面介绍如何借助流行的 CI 服务商 Travis CI 来实现。 前往 https://github.com/settings/tokens，生成一个新的个人访问令牌（personal access token）。创建时请授予 repo 权限范围，以便它拥有所需的操作权限。 用你的 GitHub 账号，把 Travis CI 应用添加到要启用的仓库。 打开你的 Travis CI 控制面板，URL 形如 https://travis-ci.com/USERNAME/REPO，然后进入仓库的 More options > Setting > Environment Variables 部分。 新建一个名为 GH_TOKEN 的环境变量，值填刚生成的令牌，再分别新建 GH_EMAIL（你的邮箱）和 GH_NAME（你的 GitHub 用户名）。 在仓库根目录创建 .travis.yml，内容如下： .travis.ymllanguage: 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` 现在，每当新的 commit 推送到 main 分支时，Travis CI 会自动运行测试套件。若所有测试通过，便会通过 `yarn deploy` 脚本将网站部署上线。 使用 Buddy 触发部署 Buddy 是一款易于上手的 CI/CD 工具，可自动将门户网站部署到不同环境，包括 GitHub Pages。 请按照以下步骤创建流水线，在推送更改至指定分支时自动部署网站的新版本： 前往 https://github.com/settings/tokens 生成一个新的 personal access token。创建时，请授予其 repo 权限，以确保具备所需的操作权限。 登录 Buddy 账户并创建一个新项目。 选择 GitHub 作为代码托管提供商，并指定包含网站代码的仓库。 在左侧导航栏切换至“流水线（Pipelines）”视图。 新建一条流水线，定义其名称，将触发模式设为“On push”（推送时），并选择作为触发条件的分支。 添加一个 Node.js 操作。 在该操作的终端中输入以下命令： `GIT_USER=- 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
使用 Drone 创建一个新的 SSH 密钥作为项目的部署密钥。 为私钥和公钥命名时要具体明确，避免覆盖已有的其他 SSH 密钥。 访问 https://github.com/USERNAME/REPO/settings/keys，粘贴刚生成的公钥来添加一个新的部署密钥。 打开 Drone.io 仪表盘并登录。URL 格式类似 https://cloud.drone.io/USERNAME/REPO。 点击目标仓库，选择“activate repository”（激活仓库），并添加名为 git_deploy_private_key 的 secret（机密），值为你刚生成的私钥内容。 在仓库根目录创建 .drone.yml 文件，内容如下。 .drone.ymlkind: 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 任务以发布你的网站。 部署到 Koyeb Koyeb 是一个面向开发者的 Serverless 平台，支持全球应用部署。它允许你无缝运行 Docker 容器、Web 应用和 API，并提供基于 Git 的部署、原生自动扩缩容、全球边缘网络以及内置的服务网格与发现功能。你可以参考 Koyeb 的 Docusaurus 部署指南快速上手。 部署到 Render Render 提供免费的静态站点托管，包含全托管 SSL、自定义域名、全球 CDN 以及从 Git 仓库进行的持续自动部署。跟随 Render 部署 Docusaurus 的指南，只需几分钟即可完成配置。 部署到 Qovery Qovery 是一个全托管云平台，运行在你的 AWS、Digital Ocean 或 Scaleway 账户上，让你可以在一个地方托管静态站点、后端 API、数据库、定时任务以及其他所有应用。 创建一个 Qovery 账户。如果你还没有账户，请访问 Qovery 仪表盘创建。 创建一个项目。 点击 Create project 并为项目命名。 点击 Next。 创建新环境。 点击 Create environment 并命名环境（例如 staging、production）。 添加应用。 点击 Create an application，输入名称，并选择存放 Docusaurus 应用的 GitHub 或 GitLab 仓库。 定义主分支名称和根应用路径。 点击 Create。应用创建完成后： 导航至应用 Settings 选择 Port 添加 Docusaurus 应用使用的端口 一键部署 现在只需导航到应用页面并点击 Deploy。 就这样。监控状态直至应用部署完成。要在浏览器中打开应用，请在应用概览中点击 Action 并选择 Open。 部署到 Hostman Hostman 允许你免费托管静态网站。它实现了全流程自动化，你只需连接仓库并跟随简单步骤即可： 创建服务。 要部署 Docusaurus 静态网站，请在仪表盘左上角点击 Create，并选择 Front-end app 或 static website。 选择要部署的项目。 如果你使用 GitHub、GitLab 或 Bitbucket 账户登录 Hostman，此时将看到包含私有仓库在内的项目列表。 选择你要部署的项目。该目录必须包含项目文件（例如 website）。 如需访问其他仓库，请点击 Connect another repository。 如果你未使用 Git 账户凭据登录，现在可以访问相应账户并选择项目。 配置构建设置。 接下来会出现 Website customization 窗口。请从框架列表中选择 Static website 选项。 Directory with app 指向构建完成后包含项目文件的目录。如果在第 2 步中选择了包含网站内容（或 my_website）目录的仓库，则此项可以留空。 Docusaurus 的标准构建命令为： npmYarnpnpmBunnpm run build
yarn build
pnpm run build
bun run build
必要时可修改构建命令，支持用 && 分隔多个指令。 部署 点击 Deploy 启动构建流程。开始后即可查看部署日志。若代码存在问题，日志中会显示警告或错误信息并说明原因。通常情况下，日志包含调试所需的全部数据。 部署完成后，你会收到邮件通知及日志记录。至此项目上线完毕，即刻可用。 部署到 Surge Surge 是静态网站托管平台，支持通过命令行在一分钟内部署 Docusaurus 项目。操作简单且免费（含自定义域名及 SSL）。 按以下步骤使用 Surge 在数秒内完成部署： 首先，运行以下命令通过 npm 安装 Surge： npmYarnpnpmBunnpm install -g surge
yarn global add surge
pnpm add -g surge
bun add --global surge
在项目根目录下运行以下命令以生成生产环境静态文件： npmYarnpnpmBunnpm run build
yarn build
pnpm run build
bun run build
然后在项目根目录下运行： 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 命令即可部署其他变更。 部署到 QuantCDN 安装 Quant CLI 注册 QuantCDN 账户 运行 quant init 初始化项目并填入凭据： quant init
部署站点。 quant deploy
更多部署到 QuantCDN 的示例和用例，请参阅文档和博客。 部署到 Layer0 Layer0 是一个一体化平台，可用于开发、部署、预览、实验、监控和运行无头前端。它专注于大型动态网站，通过 EdgeJS（基于 JavaScript 的 CDN）、预测性预取和性能监控实现一流的性能。Layer0 提供免费套餐，按照 Layer0 的 Docusaurus 部署指南操作，几分钟即可上手。 部署到 Cloudflare Pages Cloudflare Pages 是一个面向前端开发者的 Jamstack 平台，支持协作和网站部署。按照这篇文章操作，几分钟即可上手。 部署到 Azure Static Web Apps Azure Static Web Apps 是一项服务，可以直接从代码仓库自动构建全栈 Web 应用并部署到 Azure，简化 CI/CD 的开发体验。它将 Web 应用的静态资源与动态（API）端点分开：静态资源由全球分布式的内容服务器提供，客户端可以从附近的服务器更快地获取文件；动态 API 则采用事件驱动的 Serverless 函数架构，更具成本效益并按需扩展。按照这份分步指南操作，几分钟即可上手。
