部署
要为生产环境构建网站的静态文件,请运行:
- 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
中,下面这些参数是必填的,让 Docusaurus 能够优化路由,并从正确的位置加载文件:
参数 | 描述 |
---|---|
url | 站点 URL。 如果网站部署在 https://my-org.com/my-project/ , url 就是 https://my-org.com/ |
baseUrl | 站点的 base 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
站点默认会部署在 http://localhost:3000/
。
末尾斜杠配置
Docusaurus 有一个 trailingSlash
配置,允许你自定义 URL 链接和输出的文件名格式。
你一般不需要修改默认值。 遗憾的是,每家静态托管商的行为都不一样,而把同一网站部署到不同服务商的结果可能大相径庭。 根据你的托管商的不同,你可能需要修改此配置。
要更好地了解你的托管商的行为,可以参见 slorber/trailing-slash-guide,并依此配置 trailingSlash
选项。
使用环境变量
把可能敏感的信息放在环境变量中的做法很常见。 然而,在典型的 Docusaurus 网站中, docusauurus.config.js
文件是唯一一个可以接触到 Node.js 环境的地方(参见我们的架构概述)。除此之外的所有东西(MDX 页面,React 组件等等),都处于客户端中,不能直接访问 process
全局变量。 在这种情况下,你可以考虑使用 customFields
将环境变量传递给客户端。
// 如果你正在使用 dotenv (https://www.npmjs.com/package/dotenv)
import 'dotenv/config';
export default {
title: '...',
url: process.env.URL, // 你也可以通过环境变量来控制站点细节
customFields: {
// 把你的自定义环境放在这里
teamEmail: process.env.EMAIL,
},
};
import useDocusaurusContext from '@docusaurus/useDocusaurusContext';
export default function Home() {
const {
siteConfig: {customFields},
} = useDocusaurusContext();
return <div>通过 {customFields.teamEmail} 联系我们!</div>;
}
选择托管服务商
有几种常见的托管选择:
- 自行托管,借助 HTTP 服务器,例如 Apache2 和 Nginx。
- 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 页面不能做部署预览,至少方法非常复杂。 每个仓库只能和一个站点部署相关联。 另一方面,你还是可以控制哪些人有站点部署的写权限。
不存在通用方案。 你需要权衡你的需求和资源,然后再做决定。
自行托管
你可以用 docusaurus service
命令来自行托管 Docusaurus。 可以用 --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,不包含末尾斜杠
baseUrl: '/', // 你的站点相对于仓库的基目录
// ...
};
然后,用 Netlify 创建你的网站。
在设立站点时,指定如下构建指令和目录:
- 构建指令:
npm run build
- 发布目录:
build
如果你没有设置这些构建选项,你还是可以在创建站点之后前往 "Site settings" -> "Build & deploy" 完成配置。
用上述选项配置完毕后,你的网站就会在有代码合并到部署分支(默认为 main
)时自动重新部署,
某些 Docusaurus 网站把 docs
文件夹放在 website
之外(尤其是从 Docusaurus v1 迁移而来的站点):
repo # git 根目录
├── docs # MD 文件
└── website # Docusaurus 根目录
如果你选择用 website
文件夹作为 Netlify 的 base directory,那么更新 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"。
如果你想保持开启 Pretty URLs
Netlify 设置,就要适当配置 Docusaurus 的 trailingSlash
选项。
更多信息请参阅 slorber/trailing-slash-guide。
部署到 Vercel
部署 Docusaurus 项目到 Vercel 会带来多项收益,包括性能、易用性,等等。
要通过 Vercel 的 Git 集成部署你的 Docusaurus 项目,先确保项目已经被推送到了某个 Git 仓库中。
用 Import Flow 把项目导入进 Vercel。 在导入过程中,你会发现所有相关的选项都已帮你预配置好了;但你也可以选择变更这些选项中的任意选项。
项目导入完成后,所有分支的后续推送都会生成部署预览。所有生产分支(通常是 "main" 或 "master")的变更都会触发生产部署。
部署到 GitHub Pages
Docusaurus 提供了一种简单的方法来发布到 GitHub Pages。每个 GitHub 仓库都免费附送了 Github Pages。
概览
通常,发布过程会涉及到两个仓库(至少是两个分支):包含源文件的分支,以及包含将使用 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 文档了解详情。
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 网址链接添加末尾斜杠。 建议设置 trailingSlash
(true
或 false
都可以,只要不是 undefined
)。
示例:
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 源仓库。 如果源仓库的地址是 SSH URL(比如 git@github.com:facebook/docusaurus.git ),USE_SSH 会被推断为 true 。 |
GIT_USER | 用于推送部署文件的 GitHub 账户用户名,需要有部署仓库的推送权限。 对于你自己的仓库,这一般会是你自己的 GitHub 用户名。 不使用 SSH 时必填,使用 SSH 时则会被忽略。 |
GIT_PASS | GitHub 用户(GIT_USER 所指定)的 personal access token,用于非交互式部署(如持续部署) |
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 提示你输入密码时,请输入个人访问令牌。 更多信息请见 GitHub 文档。
或者,你也可以使用 SSH (USE_SSH=true
) 登录。
触发 GitHub Actions 部署
GitHub Actions 允许你在仓库中完成软件开发流程的自动化、自定义执行。
以下工作流示例假定你的网站源(文件)位于你仓库的 main
分支上( _源分支_是 main
分支),而且你的发布源已经为使用自定义 GitHub Actions 工作流进行发布配置好了。
我们的目标是:
- 当向
main
发起新的拉取请求时,有一个 action 确保网站构建成功,但不会真正部署。 这个 job 会被称为test-deploy
。 - 当一个拉取请求被合并到
main
分支,或是某人直接向main
分支推送时,站点会被构建并部署到 GitHub Pages。 这个 job 会被称为deploy
。
下面是两种通过 GitHub Actions 部署文档的方法。 根据你的部署仓库的位置,选择下面相应的选项卡:
- 源代码仓库和部署代码仓库是同一仓库。
- 部署仓库是一个远程仓库,和源仓库不同。 此方案的说明假定发布源为
gh-pages
分支。
- 同一
- 远程
虽然你可以把两个 job 定义在同一个工作流文件中,但原始的 添加这两个工作流文件: 这些文件假设你使用的是 Yarn。 如果你用的是 npm,需要把 如果你的 Docusaurus 项目不在你的仓库的根目录,你可能需要配置默认工作目录,并相应地调整路径。deploy
工作流总是会在 PR(拉取请求)的检查套件状态中被列为跳过,这不代表真实的状态,也不会为审查过程提供任何价值。 所以,我们建议把它们作为单独的工作流来管理。GitHub action 文件
cache: yarn
、yarn install --frozen-lockfile
、yarn build
分别修改成 cache: npm
、npm ci
、npm run build
。name: 部署到 GitHub Pages
on:
push:
branches:
- main
# 如果你想要进一步定义触发、路径以及其他内容,请检阅 Github Actions 文档
# https://docs.github.com/zh/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@v4name: 测试部署
on:
pull_request:
branches:
- main
# 如果你想要进一步定义触发、路径以及其他内容,请检阅 Github Actions 文档
# https://docs.github.com/zh/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 完成身份验证。
- 生成一个新 SSH 密钥。 因为这个 SSH 密钥会用在 CI 中,所以不能输入任何密码。
- 默认情况下,你的公钥应该会被创建在
~/.ssh/id_rsa.pub
中。如果没有,那么在添加 GitHub 部署密钥时,要记得使用你在前一步中提供的名字。 - 用
pbcopy < ~/.ssh/id_rsa.pub
把密钥复制到剪贴板,然后在你的部署仓库中,把它粘贴入部署密钥。 如果命令行不适合,可以手动复制文件内容。 在保存部署密钥之前,要勾选Allow write access
。 - 你需要把你的私钥设置成 GitHub secret,从而允许 Docusaurus 为你运行部署。
- 用
pbcopy < ~/.ssh/id_rsa
复制你的私钥,然后把它粘贴成一个 GitHub secret,名字叫GH_PAGES_DEPLOY
。 如果命令行不适合,可以手动复制文件内容。 保存你的 secret。 - 在
.github/workflows/
目录下创建您的文档工作流 。 在这个例子里,就是deploy.yml
。
至此,你应该已经:
- 通过把 SSH 私钥作为其 Github Secret,设置了具有 GitHub 工作流的源仓库
- 通过把 SSH 公钥添加到 GitHub 部署密钥中,设置了你的部署仓库
GitHub action 文件
请确保将 actions@github.com
替换为你的 GitHub 邮箱,并把 gh-actions
替换为你的名称。
此文件假定你使用的是 Yarn。 如果你用的是 npm,需要把 cache: yarn
、yarn install --frozen-lockfile
、yarn build
分别修改成 cache: npm
、npm ci
、npm run build
。
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-agent@v0.5.0
with:
ssh-private-key: ${{ secrets.GH_PAGES_DEPLOY }}
- name: 部署到 GitHub Pages
env:
USE_SSH: true
run: |
git config --global user.email "actions@github.com"
git config --global user.name "gh-actions"
yarn install --frozen-lockfile
yarn deploy
网站没有正确部署?
在推送到 main 分支后,如果你没有看到你的站点被发布到想要的位置(比方说,访问后发现“这里没有 Github Pages 站点”,或是显示你仓库里的 README.md 文件),尝试以下步骤:
- 等3分钟,然后刷新一下。 GitHub 页面可能需要几分钟时间才能接收到新文件。
- 检查你仓库的入口页上次提交的标题旁是否有个绿色的小对勾。如果有,那就表明 CI 通过了。 如果你看到的是一个叉,那就说明构建或者部署失败了,你应该检查日志以获取更多调试信息。
- 点击对勾,确保你看到的是“部署到 Github Pages”工作流。 如果你看到的名称是类似“pages build and deployment / deploy”(即“页面构建和部署”)这样的,这就表明你的自定义部署工作流根本无法触发。 确保对应的 YAML 文件被放置在
.github/workflows
文件夹下,同时其触发条件也被正确设置了(比如,如果你的默认分支是“master”而不是“main”,你就需要修改on.push
属性)。 - 在你仓库的 Settings > Pages 下,确保“Source”(其指的是用以_部署_的文件,不是我们术语里的“源(source)”)被设置为 “gh-pages” + “/(root)”,因为我们正在使用
gh-pages
作为部署分支。
如果你正在使用自定义域名:
- 如果你正在使用自定义域名,请验证你是否设置了正确的 DNS 记录。 请查看关于配置自定义域名的 GitHub pages 文档。 此外,请注意,DNS 修改可能需要24小时才能通过互联网传播(注:即 DNS 解析生效)。
触发 Travis CI 部署
持续集成(CI)服务通常用于每当新提交检入源代码控制(注:又称版本控制)时执行例程任务。 这些任务可以是运行单元测试、集成测试、自动化构建、发布包到 npm 和向你的网站部署变更的任意组合。 要自动化你网站的部署,你只需要每当站点更新时调用 yarn deploy
脚本。 下面的章节涵盖了如何使用 Travis CI 做到这一点。Travis CI 是一个热门的持续集成服务提供商。
- 在 https://github.com/settings/tokens 上生成一个新 personal access token。 新建令牌时,授予它
repo
权限,这样它就有所有需要的权限了。 - 用你的 GitHub 账户把 Travis CI 应用添加到你想要激活的仓库中。
- 打开你的 Travis CI 主界面。 URL 大概像
https://travisenci.com/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 上生成一个新 personal access token。 新建令牌时,授予它
repo
权限,这样它就有所有需要的权限了。 - 登录 Buddy 帐户并创建一个新项目。
- 选择 GitHub 作为 git 托管提供商,并选择包含你的网站源码的仓库。
- 在左侧的导航面板中,切换到
Pipelines
页面。 - 创建一个新的管道。 输入一个名称,把触发模式设置为
On push
,然后选择会触发管道执行的分支。 - 添加一个
Node.js
action。 - 在 action 的终端中添加以下指令:
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 上生成一个新 personal access token,包括
repo
权限。 - 在项目页面(类似
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
使用 Drone
- 创建一个新的 SSH 密钥,它会是你的项目的部署密钥。
- 命名你的私钥和公钥,确保它们不会覆盖其他 SSH 密钥。
- 在
https://github.com/USERNAME/REPO/settings/keys
上,添加一个新部署密钥,把你刚刚生成的公钥粘贴进去。 - 打开你的 Drone.io 界面并登录。 URL 看起来像
https://cloud.drone.io/USERNAME/REPO
。 - 点击仓库,点击激活仓库,并添加一个名为
git_depu_private_key
的秘密,值为你刚刚生成的私钥。 - 在仓库根目录创建一个
.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,此文件中的触发(trigger)都将启动 Drone CI 的 job,以发布你的网站。
部署到 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 job,和所有其他应用。
- 新建一个 Qovery 账户。 如果你还没有账户,可以在 Qovery 界面创建一个。
- 新建一个项目。
- 点击 Create project 并给你的项目命名。
- 点击 Next。
- 新建一个环境。
- 点击 Create environment 并给它命名(比如 staging, production 等)。
- 添加一个应用。
- 点击 Create an application,给它命名,并选择你的 Docusaurus 应用所在的 GitHub 或 GitLab 仓库。
- 定义主分支名称和应用的根目录。
- 点击 Create。 应用创建完毕后:
- 前往应用的 Settings
- 选择 Port
- 添加你的 Docusaurus 应用使用的端口
- 部署
- 你现在需要做的就是跳转到你的应用,然后点击部署(Deploy)。
设置完成! 监视状态,直到应用部署完成。 要在浏览器中打开应用,在应用概览中点击 Action 并 打开。
部署到 Hostman
Hostman 允许您免费托管静态网站。 Hostman 会自动化处理所有东西,您只需要连接仓库并完成几个简单的步骤:
-
创建一个服务。
- 要部署 Docusaurus 静态网站,点击主界面左上角的 Create,选择 Front-end app or static website。
-
选择要部署的项目。
-
如果您用 GitHub、GitLab 或 Bitbucket 账号登录 Hostman,就可以看见您的项目仓库,包括私有仓库。
-
选择您想要部署的项目。 它必须包含项目文件的目录(比如
website
)。 -
要访问另一个仓库,请点击 Connect another repository。
-
如果你没有用你的 Git 帐户登录,你现在也能访问必要的帐户,然后选择项目。
-
-
配置构建设置。
-
接下来,会出现一个 Website customization 窗口。 在框架列表中,选择 Static website 选项。
-
Directory with app 需要指向包含项目构建输出文件的目录。 如果您在步骤2中选择了带有网站内容的版本库(或
my_website
目录),您可以将其留空。 -
Docusaurus 的标准构建命令是:
- npm
- Yarn
- pnpm
- Bun
npm run build
yarn build
pnpm run build
bun run build
-
如果需要,您可以修改构建命令。 您可以输入多个命令,以
&&
分隔。
-
-
部署。
-
点击 Deploy 开始构建。
-
一旦开始,您将可以查看部署日志。 如果代码有任何问题,您将会在日志中收到警告或错误消息,指定问题的原因。 通常,日志包含您需要的所有调试数据。
-
当部署完成后,您将收到电子邮件通知,并且还会看到日志条目。 全部完成! 您的项目已经就绪。
-
部署到 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
(可以编辑)。
使用自己的域名
如果您有域名,可以通过如下指令,使用 surge 把网站部署到自定义域名:
surge build/ your-domain.com
您的网站现在被免费部署在了 subdomain.surge.sh
或 your-domain.com
上,取决于选择的方式。
配置 CNAME 文件
使用以下命令把您的域名存储在 CNAME 文件中,以供未来部署:
echo subdomain.surge.sh > CNAME
以后,您可以通过 surge
命令部署任何其他更改。
部署到 Stormkit
您可以将您的 Docusaurus 项目部署到 Stormkit, 一个用于静态网站、单页应用程序和无服务器功能的部署平台。 欲了解详细说明,请参阅此指南。
部署到 QuantCDN
请参阅文档和博客以了解更多部署到 QuantCDN 的实际用例。
部署到 Layer0
Layer0 是一个用于开发、部署、预览、实验、监视和运行无头前端的全套平台。 它侧重于大型动态网站,通过 EdgeJS(一个基于 JavaScript 的内容分发网络)、预测性预抓取和性能监测,最大化提升性能。 Layer0 提供免费服务。 跟随 Layer0 的 Docusaurus 部署指南,您可以在几分钟内上手。
部署到 Cloudflare Pages
Cloudflare Pages 是一个 Jamstack 平台,允许前端开发者协作并部署网站。 只需几分钟,按照本页面的指引即可快速上手。
部署到 Azure Static Web Apps
Azure Static Web Apps 服务允许你直接将全栈网络应用从代码仓库自动构建部署到 Azure,大大简化 CI/CD 的开发者体验。 Static Web Apps 会将网络应用的静态资源和动态 API 端点分离开来。 静态资源是从全球分布的内容服务器分发的,允许客户端通过附近的服务器更快地获取文件。 动态 API 使用无服务器架构,事件驱动,以函数为基础,更具成本效益,并能根据需要缩放。 按照这个分步骤指南,只需几分钟即可快速上手。
部署到 Kinsta
Kinsta 静态站点托管 让您免费部署最多100个静态站点。 带有SSL的自定义域名、100GB月带宽和260多个 Cloudflare CDN 位置。
只需点击几下,按照我们的 Kinsta 平台 Docusaurus 指南文章操作即可轻松上手。