部署
要为生产环境构建网站的静态文件,请运行
- npm
- Yarn
- pnpm
- Bun
npm run build
yarn build
pnpm run build
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
- Yarn
- pnpm
- Bun
npm run serve
yarn serve
pnpm run serve
bun run serve
默认情况下,这将在 https://:3000/
加载您的站点。
尾部斜杠配置
Docusaurus 有一个 trailingSlash
配置,允许自定义 URL/链接和生成的文件名模式。
默认值通常效果良好。不幸的是,每个静态托管服务提供商都具有**不同的行为**,将完全相同的站点部署到不同的主机可能会导致不同的结果。根据您的主机,更改此配置可能会很有用。
使用 slorber/trailing-slash-guide 以更好地了解您的主机的行为并适当地配置 trailingSlash
。
使用环境变量
将潜在敏感信息放入环境变量中是常见的做法。然而,在典型的 Docusaurus 网站中,docusaurus.config.js
文件是与 Node.js 环境交互的唯一接口(请参阅我们的架构概述),而其他所有内容(MDX 页面、React 组件等)都是客户端的,并且无法直接访问 process
全局变量。在这种情况下,您可以考虑使用 customFields
将环境变量传递给客户端。
// If you are using dotenv (https://npmjs.net.cn/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,但我们单独比较它)。
如果您不确定选择哪一个,请考虑以下问题
我愿意为此投入多少资源(金钱、工时等)?
- 🔴 自托管需要网络以及 Linux 和 Web 服务器管理经验。这是最困难的选项,需要最多时间才能成功管理。从费用角度来看,云服务几乎从不免费,购买/部署本地服务器甚至可能更昂贵。
- 🟢 Jamstack 提供商可以帮助您在几乎不费吹灰之力的情况下建立一个可工作的网站,并提供易于配置的服务器端重定向等功能。许多提供商即使对于免费计划也提供慷慨的构建时间配额,您几乎永远不会超出这些配额。然而,免费计划有其限制,一旦达到这些限制,您就需要付费。请查阅您的提供商的定价页面以获取详细信息。
- 🟡 GitHub Pages 部署工作流设置起来可能很繁琐。(证据:请参阅部署到 GitHub Pages 的篇幅!)但是,此服务(包括构建和部署)对于公共仓库始终是免费的,我们提供了详细的说明来帮助您使其工作。
我需要多少服务器端自定义?
- 🟢 通过自托管,您可以访问整个服务器的配置。您可以配置虚拟主机以根据请求 URL 提供不同的内容,您可以执行复杂的服务器端重定向,您可以实现身份验证等等。如果您需要大量服务器端功能,请自托管您的网站。
- 🟡 Jamstack 通常提供一些服务器端配置(例如 URL 格式(尾部斜杠)、服务器端重定向等)。
- 🔴 GitHub Pages 除了强制执行 HTTPS 和设置 CNAME 记录之外,不公开服务器端配置。
我需要协作友好的部署工作流吗?
- 🟡 自托管服务可以利用像 Netlify 这样的持续部署功能,但涉及更多繁重的工作。通常,您会指定一个特定的人来管理部署,并且工作流不会像其他两种选项那样非常基于 Git。
- 🟢 Netlify 和 Vercel 为每个拉取请求提供部署预览,这对于团队在合并到生产环境之前审查工作很有用。您还可以管理一个团队,对部署进行不同的成员访问控制。
- 🟡 GitHub Pages 无法以不复杂的方式进行部署预览。一个仓库只能与一个站点部署相关联。另一方面,您可以控制谁对站点的部署具有写入访问权限。
没有万能的解决方案。您需要在做出选择之前权衡您的需求和资源。
自托管
Docusaurus 可以使用 docusaurus serve
进行自托管。使用 --port
更改端口,使用 --host
更改主机。
- npm
- Yarn
- pnpm
- Bun
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
bun run serve --build --port 80 --host 0.0.0.0
与静态托管服务提供商/CDN 相比,这不是最佳选择。
在以下部分中,我们将介绍一些常见的托管服务提供商以及如何配置它们以最有效地部署 Docusaurus 站点。Docusaurus 不隶属于任何这些服务,此信息仅供方便之用。一些撰写内容由第三方提供,最近的 API 更改可能未在我们这边反映。如果您看到过时内容,欢迎提交 PR。
由于我们只能尽力提供此内容,我们已停止接受添加新托管选项的 PR。但是,您可以在单独的站点(例如您的博客或提供商的官方网站)上发布您的文章,并要求我们包含指向您文章的链接。
部署到 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
// ...
};
在设置站点时,按如下方式指定构建命令和目录
- 构建命令:
npm run build
- 发布目录:
build
如果您没有配置这些构建选项,您仍然可以在站点创建后前往“站点设置”->“构建和部署”。
一旦使用上述选项正确配置,您的站点应在合并到您的部署分支(默认为 main
)时部署并自动重新部署。
一些 Docusaurus 站点将 docs
文件夹放在 website
之外(很可能是 Docusaurus v1 站点)
repo # git root
├── docs # MD files
└── website # Docusaurus root
如果您决定使用 website
文件夹作为 Netlify 的基本目录,当您更新 docs
文件夹时,Netlify 将不会触发构建,并且您需要配置一个自定义的 ignore
命令
[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
设置。请务必**单独取消选中它**。
如果您想保持 Pretty Urls
Netlify 设置开启,请适当地调整 trailingSlash
Docusaurus 配置。
有关更多信息,请参阅 slorber/trailing-slash-guide。
部署到 Vercel
将您的 Docusaurus 项目部署到 Vercel 将在性能和易用性方面为您提供各种优势。
要使用 Vercel for Git 集成部署您的 Docusaurus 项目,请确保它已推送到 Git 仓库。
使用导入流程将项目导入 Vercel。在导入过程中,您会发现所有相关选项都已为您预先配置;但是,您可以选择更改其中任何选项。
项目导入后,所有后续推送到分支的操作都将生成预览部署,并且对生产分支(通常是“main”或“master”)所做的所有更改都将导致生产部署。
部署到 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/'
更改回 baseUrl: '/'
,并将其 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
)。
示例
export default {
// ...
url: 'https://endiliey.github.io', // Your website 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 企业版主机设置为环境变量
名称 | 描述 |
---|---|
GITHUB_HOST | 您的 GitHub 企业版站点的域名。 |
GITHUB_PORT | 您的 GitHub 企业版站点的端口。 |
部署
最后,要将您的站点部署到 GitHub Pages,请运行
- Bash
- Windows
- PowerShell
GIT_USER=<GITHUB_USERNAME> yarn deploy
cmd /C "set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy"
cmd /C 'set "GIT_USER=<GITHUB_USERNAME>" && yarn deploy'
从 2021 年 8 月开始,GitHub 要求每次命令行登录都使用**个人访问令牌**而不是密码。当 GitHub 提示您输入密码时,请输入 PAT。有关更多信息,请参阅 GitHub 文档。
或者,您可以使用 SSH(USE_SSH=true
)登录。
使用 GitHub Actions 触发部署
GitHub Actions 允许您直接在仓库中自动化、自定义和执行您的软件开发工作流。
下面的工作流示例假设您的网站源位于仓库的 main
分支(源分支是 main
),并且您的发布源已配置为通过自定义 GitHub Actions 工作流进行发布。
我们的目标是
- 当向
main
发起新的拉取请求时,会有一个操作确保站点成功构建,而无需实际部署。此作业将被称为test-deploy
。 - 当拉取请求合并到
main
分支或有人直接推送到main
分支时,它将被构建并部署到 GitHub Pages。此作业将被称为deploy
。
这里有两种使用 GitHub Actions 部署文档的方法。根据您的部署仓库的位置,选择下面的相关标签
- 源仓库和部署仓库是**同一个**仓库。
- 部署仓库是一个**远程**仓库,与源仓库不同。此场景的说明假设发布源是
gh-pages
分支。
- 相同
- 远程
虽然您可以在同一个工作流文件中定义这两个作业,但原始的 deploy
工作流将始终在 PR 检查套件状态中显示为跳过,这不指示实际状态,也对审查过程没有价值。因此,我们建议将它们作为单独的工作流进行管理。
GitHub action 文件
添加这两个工作流文件
如果您的 Docusaurus 项目不在仓库的根目录,您可能需要配置一个默认工作目录,并相应地调整路径。
- npm
- Yarn
name: Deploy to GitHub Pages
on:
push:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://githubdocs.cn/en/actions/using-workflows/workflow-syntax-for-github-actions#on
jobs:
build:
name: Build 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: Install dependencies
run: npm ci
- name: Build website
run: npm run build
- name: Upload Build Artifact
uses: actions/upload-pages-artifact@v3
with:
path: build
deploy:
name: Deploy to GitHub Pages
needs: build
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
permissions:
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source
# Deploy to the github-pages environment
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
name: Test deployment
on:
pull_request:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://githubdocs.cn/en/actions/using-workflows/workflow-syntax-for-github-actions#on
jobs:
test-deploy:
name: Test deployment
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: Install dependencies
run: npm ci
- name: Test build website
run: npm run build
name: Deploy to GitHub Pages
on:
push:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://githubdocs.cn/en/actions/using-workflows/workflow-syntax-for-github-actions#on
jobs:
build:
name: Build 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: Install dependencies
run: yarn install --frozen-lockfile
- name: Build website
run: yarn build
- name: Upload Build Artifact
uses: actions/upload-pages-artifact@v3
with:
path: build
deploy:
name: Deploy to GitHub Pages
needs: build
# Grant GITHUB_TOKEN the permissions required to make a Pages deployment
permissions:
pages: write # to deploy to Pages
id-token: write # to verify the deployment originates from an appropriate source
# Deploy to the github-pages environment
environment:
name: github-pages
url: ${{ steps.deployment.outputs.page_url }}
runs-on: ubuntu-latest
steps:
- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
name: Test deployment
on:
pull_request:
branches:
- main
# Review gh actions docs if you want to further define triggers, paths, etc
# https://githubdocs.cn/en/actions/using-workflows/workflow-syntax-for-github-actions#on
jobs:
test-deploy:
name: Test deployment
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: Install dependencies
run: yarn install --frozen-lockfile
- name: Test build website
run: yarn build
跨仓库发布设置起来更困难,因为您需要推送到另一个具有权限检查的仓库。我们将使用 SSH 进行身份验证。
- 生成新的 SSH 密钥。由于此 SSH 密钥将在 CI 中使用,请确保不要输入任何密码。
- 默认情况下,您的公钥应已在
~/.ssh/id_rsa.pub
中创建;否则,使用您在上一步中提供的名称将您的密钥添加到GitHub 部署密钥。 - 使用
pbcopy < ~/.ssh/id_rsa.pub
将密钥复制到剪贴板,并将其作为部署密钥粘贴到部署仓库中。如果命令行对您不起作用,请复制文件内容。在保存部署密钥之前,选中Allow write access
框。 - 您需要将私钥作为 GitHub secret,以允许 Docusaurus 为您运行部署。
- 使用
pbcopy < ~/.ssh/id_rsa
复制您的私钥,并在源仓库中粘贴一个名为GH_PAGES_DEPLOY
的 GitHub secret。如果命令行对您不起作用,请复制文件内容。保存您的 secret。 - 在
.github/workflows/
目录中创建您的文档工作流。在此示例中,它是deploy.yml
文件。
此时,您应该有
- 源仓库,其中 GitHub 工作流已将私有 SSH 密钥设置为 GitHub Secret,并且
- 您的部署仓库已在 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
。
name: 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@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
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@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: 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
站点未正确部署?
推送到 main
后,如果您没有在所需位置看到您的站点已发布(例如,显示“此处没有 GitHub Pages 站点”,或者显示您仓库的 README.md 文件),请尝试以下操作
- 等待大约三分钟并刷新。GitHub Pages 可能需要几分钟才能获取新文件。
- 检查您仓库的登录页面,查看最后一次提交标题旁边是否有绿色小勾,表示 CI 已通过。如果您看到一个叉,则表示构建或部署失败,您应该检查日志以获取更多调试信息。
- 点击该勾,并确保您看到一个“部署到 GitHub Pages”工作流。诸如“pages build and deployment / deploy”之类的名称是 GitHub 的默认工作流,表明您的自定义部署工作流根本未能触发。请确保 YAML 文件放置在
.github/workflows
文件夹下,并且触发条件设置正确(例如,如果您的默认分支是“master”而不是“main”,您需要更改on.push
属性)。 - 在您仓库的“Settings > Pages”下,确保“Source”(这是部署文件的源,而不是我们术语中的“source”)设置为“gh-pages”+“/ (root)”,因为我们正在使用
gh-pages
作为部署分支。
如果您使用自定义域
- 如果您使用自定义域,请验证您是否设置了正确的 DNS 记录。请参阅 GitHub Pages 关于配置自定义域的文档。此外,请注意 DNS 更改可能需要长达 24 小时才能在互联网上传播。
使用 Travis CI 触发部署
持续集成(CI)服务通常用于在将新提交检入版本控制时执行例行任务。这些任务可以是运行单元测试和集成测试、自动化构建、将包发布到 npm 以及将更改部署到您的网站的任意组合。要自动化网站的部署,您只需在网站更新时调用 yarn deploy
脚本。以下部分介绍了如何使用 Travis CI(一个流行的持续集成服务提供商)完成此操作。
- 前往 https://github.com/settings/tokens 并生成一个新的个人访问令牌。创建令牌时,授予它
repo
范围,以便它拥有所需的权限。 - 使用您的 GitHub 帐户,将 Travis CI 应用添加到您要激活的仓库。
- 打开您的 Travis CI 仪表板。URL 类似于
https://travis-ci.cn/USERNAME/REPO
,然后导航到您仓库的More options > Setting > Environment Variables
部分。 - 创建一个名为
GH_TOKEN
的新环境变量,其值为您新生成的令牌,然后是GH_EMAIL
(您的电子邮件地址)和GH_NAME
(您的 GitHub 用户名)。 - 在您的仓库根目录创建
.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。
按照以下步骤创建一个管道,每当您将更改推送到项目的所选分支时,该管道都会自动部署您网站的新版本
- 前往 https://github.com/settings/tokens 并生成一个新的个人访问令牌。创建令牌时,授予它
repo
范围,以便它拥有所需的权限。 - 登录您的 Buddy 帐户并创建一个新项目。
- 选择 GitHub 作为您的 Git 托管提供商,并选择包含您网站代码的仓库。
- 使用左侧导航面板,切换到
Pipelines
视图。 - 创建新管道。定义其名称,将触发模式设置为
On push
,并选择触发管道执行的分支。 - 添加一个
Node.js
操作。 - 在操作的终端中添加这些命令
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
- 如果您尚未注册,请在 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
的文件。
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
使用 Drone
- 创建一个新的 SSH 密钥,它将作为您项目的部署密钥。
- 命名您的私钥和公钥时要具体,这样它们就不会覆盖您的其他SSH 密钥。
- 前往
https://github.com/USERNAME/REPO/settings/keys
,并通过粘贴您刚刚生成的公钥来添加新的部署密钥。 - 打开您的 Drone.io 仪表板并登录。URL 类似于
https://cloud.drone.io/USERNAME/REPO
。 - 点击仓库,点击激活仓库,然后添加一个名为
git_deploy_private_key
的 secret,其值为您刚刚生成的私钥。 - 在您的仓库根目录创建
.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 是一个开发者友好的无服务器平台,用于在全球部署应用程序。该平台让您可以通过基于 Git 的部署、本机自动扩缩、全球边缘网络以及内置的服务网格和发现无缝运行 Docker 容器、Web 应用程序和 API。请查看Koyeb 的 Docusaurus 部署指南以开始使用。
部署到 Render
Render 提供免费的静态站点托管,包含完全托管的 SSL、自定义域、全球 CDN 以及从您的 Git 仓库持续自动部署。按照Render 的 Docusaurus 部署指南,只需几分钟即可开始使用。
部署到 Qovery
Qovery 是一个完全托管的云平台,运行在您的 AWS、Digital Ocean 和 Scaleway 账户上,您可以在其中托管静态站点、后端 API、数据库、cron 作业以及所有其他应用程序。
- 创建 Qovery 帐户。如果您还没有帐户,请访问Qovery 仪表板创建帐户。
- 创建项目。
- 点击**创建项目**并为您的项目命名。
- 点击**下一步**。
- 创建新环境。
- 点击**创建环境**并命名(例如 staging, production)。
- 添加应用程序。
- 点击**创建应用程序**,命名并选择您的 Docusaurus 应用程序所在的 GitHub 或 GitLab 仓库。
- 定义主分支名称和根应用程序路径。
- 点击**创建**。应用程序创建后
- 导航到您的应用程序**设置**
- 选择**端口**
- 添加 Docusaurus 应用程序使用的端口
- 部署
- 现在您只需导航到您的应用程序并点击**部署**。
就这样。查看状态并等待应用程序部署完成。要在浏览器中打开应用程序,请在您的应用程序概述中点击**操作**并**打开**。
部署到 Hostman
Hostman 允许您免费托管静态网站。Hostman 自动化一切,您只需连接您的仓库并遵循这些简单步骤
-
创建服务。
- 要部署 Docusaurus 静态网站,请点击您的仪表板左上角的**创建**并选择**前端应用或静态网站**。
-
选择要部署的项目。
-
如果您使用 GitHub、GitLab 或 Bitbucket 帐户登录 Hostman,您将看到包含您项目的仓库,包括私有仓库。
-
选择您要部署的项目。它必须包含项目文件所在的目录(例如
website
)。 -
要访问其他仓库,请点击**连接另一个仓库**。
-
如果您没有使用 Git 帐户凭据登录,您现在将能够访问所需的帐户,然后选择项目。
-
-
配置构建设置。
-
接下来,将出现“网站自定义”窗口。从框架列表中选择**静态网站**选项。
-
“应用程序目录”指向构建后将包含项目文件的目录。如果在第 2 步中选择了包含
website
(或my_website
)目录内容的仓库,则可以将其留空。 -
Docusaurus 的标准构建命令是
- npm
- Yarn
- pnpm
- Bun
npm run build
yarn build
pnpm run build
bun run build
-
如果需要,您可以修改构建命令。您可以输入多个命令,用
&&
分隔。
-
-
部署。
-
点击**部署**以开始构建过程。
-
开始后,您将进入部署日志。如果代码有任何问题,您将在日志中收到警告或错误消息,指明问题原因。通常,日志包含您所需的所有调试数据。
-
部署完成后,您将收到电子邮件通知并看到日志条目。大功告成!您的项目已上线并准备就绪。
-
部署到 Surge
Surge 是一个静态网页托管平台,您可以在几秒钟内从命令行部署您的 Docusaurus 项目。将您的项目部署到 Surge 既简单又免费(包括自定义域和 SSL 证书)。
使用 Surge 按照以下步骤在几秒钟内部署您的应用程序
- 首先,使用 npm 运行以下命令安装 Surge
- npm
- Yarn
- pnpm
- Bun
npm install -g surge
yarn global add surge
pnpm add -g surge
bun add --global surge
- 要在项目根目录中为生产环境构建您的站点的静态文件,请运行
- npm
- Yarn
- pnpm
- Bun
npm run build
yarn build
pnpm run build
bun run build
- 然后,在您的项目根目录中运行此命令
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,一个用于静态网站、单页应用程序(SPA)和无服务器函数的部署平台。有关详细说明,请参阅此指南。
部署到 QuantCDN
有关部署到 QuantCDN 的更多示例和用例,请参阅文档和博客。
部署到 Cloudflare Pages
Cloudflare Pages 是一个 Jamstack 平台,供前端开发者协作和部署网站。遵循此页面,在几分钟内即可开始使用。
部署到 Azure Static Web Apps
Azure Static Web Apps 是一项服务,可直接从代码仓库自动构建并将全栈 Web 应用程序部署到 Azure,从而简化 CI/CD 的开发者体验。静态 Web Apps 将 Web 应用程序的静态资产与其动态(API)端点分离。静态资产从全球分布式内容服务器提供,使客户端能够更快地使用附近的服务器检索文件。动态 API 通过无服务器架构进行扩展,采用事件驱动的基于函数的方法,更具成本效益并可按需扩展。遵循此分步指南,在几分钟内即可开始使用。
部署到 Kinsta
Kinsta 静态站点托管允许您免费部署多达 100 个静态站点,提供带 SSL 的自定义域、100 GB 每月带宽以及 260 多个 Cloudflare CDN 位置。
只需点击几下即可开始使用,请参阅我们关于在 Kinsta 上部署 Docusaurus 的文章。