部署
要为生产环境构建网站的静态文件,请运行:
- npm
- Yarn
- pnpm
npm run build
yarn build
pnpm run build
Once it finishes, the static files will be generated within the build
directory.
The only responsibility of Docusaurus is to build your site and emit static files in build
.
现在,该由你来决定怎么托管这些静态文件了。
You can deploy your site to static site hosting services such as Vercel, GitHub Pages, Netlify, Render, Surge...
Docusaurus 网站是静态渲染的,而且一般不需要 JavaScript 也能运行!
Configuration
The following parameters are required in docusaurus.config.js
to optimize routing and serve files from the correct location:
参数 | 描述 |
---|---|
url | 站点 URL。 For a site deployed at https://my-org.com/my-project/ , url is https://my-org.com/ . |
baseUrl | 站点的 base URL,带有末尾斜杠。 For a site deployed at https://my-org.com/my-project/ , baseUrl is /my-project/ . |
Testing your Build Locally
在部署到生产环境前,事先进行本地测试尤为重要。 Docusaurus provides a docusaurus serve
command for that:
- npm
- Yarn
- pnpm
npm run serve
yarn serve
pnpm run serve
By default, this will load your site at http://localhost:3000/
.
Trailing slash configuration
Docusaurus has a trailingSlash
config, to allow customizing URLs/links and emitted filename patterns.
你一般不需要修改默认值。 Unfortunately, each static hosting provider has a different behavior, and deploying the exact same site to various hosts can lead to distinct results. 根据你的托管商的不同,你可能需 要修改此配置。
Use slorber/trailing-slash-guide to understand better the behavior of your host and configure trailingSlash
appropriately.
Using environment variables
把可能敏感的信息放在环境变量中的做法很常见。 However, in a typical Docusaurus website, the docusaurus.config.js
file is the only interface to the Node.js environment (see our architecture overview), while everything else—MDX pages, React components... are client side and do not have direct access to the process
global. In this case, you can consider using customFields
to pass environment variables to the client side.
// 如果你用 dotenv (https://www.npmjs.com/package/dotenv)
require('dotenv').config();
module.exports = {
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>Contact us through {customFields.teamEmail}!</div>;
}
Choosing a hosting provider
有几种常见的托管选择:
- Self hosting with an HTTP server like Apache2 or Nginx;
- Jamstack providers, e.g. Netlify and Vercel. 我们会以它们为参考,但同样的道理也可以适用于其他提供商。
- GitHub Pages. (从定义上说,它也是 Jamstack,但我们会单独比较它。)
如果你不清楚选择哪一个,问自己下面几个问题:
How much resource (person-hours, money) am I willing to invest in this?
- 🔴 自行托管是最难设置的——通常需要一个富有经验的人来管理。 云服务几乎永远不是免费的,而搭建一个本地服务器并把它连接到广域网可能更加昂贵。
- 🟢 Jamstack 提供商可以帮助你建立一个运转良好的网站,几乎不需要时间,并且很容易配置功能,比如服务端重定向。 许多提供商的构建时间配额非常慷慨,甚至免费套餐也够用,你几乎永远不会超出配额。 然而它最终还是有限的——一旦达到限额,就需要付款。 要了解详情,请查看你的提供商的定价页面。
- 🟡 GitHub Pages 部署的工作流程设置起来可能很麻烦。 (Evidence: see the length of Deploying to GitHub Pages!) 但是,这项服务(包括构建和部署)对所有公共 仓库都永久免费,并且我们也有详细教程,帮助你正确运行它。
How much server-side configuration would I need?
- 🟢 自行托管时,你可以控制整个服务器的配置。 你可以根据请求的 URL 配置虚拟主机提供不同的服务;你可以做复杂的服务端重定向;你可以把部分网站设置成认证后访问…… 如果你需要很多服务器端功能,请选择自行托管网站。
- 🟡 Jamstack 通常会提供一些服务器端配置,比如 URL 格式化(是否带有末尾斜杠)、服务端重定向等。
- 🔴 GitHub 页面除了使用 HTTPS 和设置 CNAME 以外,没有暴露任何服务器端的配置。
Do I have needs to cooperate?
- 🟡 自行托管可以达到和 Netlify 一样的效果,但为此付出的工作要多得多。 通常,你会有一个特定的人负责部署,而且相比于其他两个选项,工作流程也不会非常基于 Git。
- 🟢 Netlify 和 Vercel 对每个 Pull Request 都会生成部署预览,这对于在合并到生产环境之前的团队审核工作非常有用。 你也可以做团队管理,不同成员拥有不同的部署访问权限。
- 🟡 GitHub 页面不能做部署预览,至少方法非常复杂。 每个仓库只能和一个站点部署相关联。 另一方面,你还是可以控制哪些人有站点部署的写权限。
不存在通用方案。 你需要权衡你的需求和资源,然后再做决定。
Self-Hosting
Docusaurus can be self-hosted using docusaurus serve
. Change port using --port
and --host
to change host.
- npm
- Yarn
- pnpm
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
相较于其他静态托管提供商 / CDN,这不是最佳解决方案。
在后面几节中,我们会介绍几个常用的托管提供商,以及如何做最有效的 Docusaurus 部署设置。 有些教程是由外部贡献者提供的。 Docusaurus 和任何服务都不利益相关。 文档可能不是最新的:服务提供商的后续 API 变更可能没有在本文档中有所反映。 如果你发现了过时的内容,欢迎来提 PR。
鉴于同样的文档更新问题,我们不再接受添加新托管方案的 PR 了。 不过你可以在其他网站上写一篇关于某个服务提供商的文章(比如你的博客,或者提供商官网),然后让我们添加一个这篇文章的链接。
Deploying to Netlify
To deploy your Docusaurus 2 sites to Netlify, first make sure the following options are properly configured:
module.exports = {
url: 'https://docusaurus-2.netlify.app', // Url to your site with no trailing slash
baseUrl: '/', // Base directory of your site relative to your repo
// ...
};
Then, create your site with Netlify.
在设立站点时,指定如下构建指令和目录:
- build command:
npm run build
- publish directory:
build
If you did not configure these build options, you may still go to "Site settings" -> "Build & deploy" after your site is created.
Once properly configured with the above options, your site should deploy and automatically redeploy upon merging to your deploy branch, which defaults to main
.
Some Docusaurus sites put the docs
folder outside of website
(most likely former Docusaurus v1 sites):
repo # git 根目录
├── docs # MD 文件
└── website # Docusaurus 根目录
If you decide to use the website
folder as Netlify's base directory, Netlify will not trigger builds when you update the docs
folder, and you need to configure a custom ignore
command:
[build]
ignore = "git diff --quiet $CACHED_COMMIT_REF $COMMIT_REF . ../docs/"
默认情况下,Netlify 会为 Docusaurus URL 添加末尾斜杠。
It is recommended to disable the Netlify setting Post Processing > Asset Optimization > Pretty Urls
to prevent lowercased URLs, unnecessary redirects, and 404 errors.
Be very careful: the Disable asset optimization
global checkbox is broken and does not really disable the Pretty URLs
setting in practice. Please make sure to uncheck it independently.
If you want to keep the Pretty Urls
Netlify setting on, adjust the trailingSlash
Docusaurus config appropriately.
Refer to slorber/trailing-slash-guide for more information.
Deploying to Vercel
Deploying your Docusaurus project to Vercel will provide you with various benefits in the areas of performance and ease of use.
To deploy your Docusaurus project with a Vercel for Git Integration, make sure it has been pushed to a Git repository.
Import the project into Vercel using the Import Flow. During the import, you will find all relevant options preconfigured for you; however, you can choose to change any of these options, a list of which can be found here.
After your project has been imported, all subsequent pushes to branches will generate Preview Deployments, and all changes made to the Production Branch (usually "main" or "master") will result in a Production Deployment.
Deploying to GitHub Pages
Docusaurus provides an easy way to publish to GitHub Pages, which comes for free with every GitHub repository.
Overview
通常发布过程会涉及两个仓库(至少是两个分支):包含源文件的分支,和包含要被部署到 GitHub Pages 上的构建输出的分支。 In the following tutorial, they will be referred to as "source" and "deployment", respectively.
每个 GitHub 仓库都关联有一个 GitHub Pages 服务。 If the deployment repository is called my-org/my-project
(where my-org
is the organization name or username), the deployed site will appear at https://my-org.github.io/my-project/
. Specially, if the deployment repository is called my-org/my-org.github.io
(the organization GitHub Pages repo), the site will appear at https://my-org.github.io/
.
In case you want to use your custom domain for GitHub Pages, create a CNAME
file in the static
directory. Anything within the static
directory will be copied to the root of the build
directory for deployment. When using a custom domain, you should be able to move back from baseUrl: '/projectName/'
to baseUrl: '/'
, and also set your url
to your custom domain.
You may refer to GitHub Pages' documentation User, Organization, and Project Pages for more details.
GitHub Pages picks up deploy-ready files (the output from docusaurus build
) from the default branch (master
/ main
, usually) or the gh-pages
branch, and either from the root or the /docs
folder. You can configure that through Settings > Pages
in your repository. 这个分支会被称作「部署分支」。
We provide a docusaurus deploy
command that helps you deploy your site from the source branch to the deployment branch in one command: clone, build, and commit.
docusaurus.config.js
settings
First, modify your docusaurus.config.js
and add the following params:
参数 | 描述 |
---|---|
organizationName | 拥有部署仓库的 GitHub 用户或组织。 |
projectName | 部署仓库的名字。 |
deploymentBranch | 部署分支的名字。 Defaults to 'gh-pages' for non-organization GitHub Pages repos (projectName not ending in .github.io ). 否则,这个字段需要明确通过配置文件或环境变量定义。 |
These fields also have their environment variable counterparts, which have a higher priority: ORGANIZATION_NAME
, PROJECT_NAME
, and DEPLOYMENT_BRANCH
.
GitHub Pages 默认为 Docusaurus 网址链接添加末尾斜杠。 It is recommended to set a trailingSlash
config (true
or false
, not undefined
).
示例:
module.exports = {
// ...
url: 'https://endiliey.github.io', // Your website URL
baseUrl: '/',
projectName: 'endiliey.github.io',
organizationName: 'endiliey',
trailingSlash: false,
// ...
};
By default, GitHub Pages runs published files through Jekyll. Since Jekyll will discard any files that begin with _
, it is recommended that you disable Jekyll by adding an empty file named .nojekyll
file to your static
directory.
Environment settings
参数 | 描述 |
---|---|
USE_SSH | Set to true to use SSH instead of the default HTTPS for the connection to the GitHub repo. If the source repo URL is an SSH URL (e.g. [email protected]:facebook/docusaurus.git ), USE_SSH is inferred to be true . |
GIT_USER | The username for a GitHub account that has push access to the deployment repo. 对于你自己的仓库,这一般会是你自己的 GitHub 用户名。 不使用 SSH 时必填,使用 SSH 时则会被忽略。 |
GIT_PASS | Personal access token of the git user (specified by GIT_USER ), to facilitate non-interactive deployment (e.g. continuous deployment) |
CURRENT_BRANCH | 源分支。 Usually, the branch will be main or master , but it could be any branch except for gh-pages . If nothing is set for this variable, then the current branch from which docusaurus deploy is invoked will be used. |
GitHub 企业安装版应该和 github.com 的工作方式一致。你只需要在环境变量中设置组织的 GitHub 企业主机即可。
参数 | 描述 |
---|---|
GITHUB_HOST | 你的 GitHub 企业网站的域名。 |
GITHUB_PORT | 你的 GitHub 企业网站的端口。 |
Deploy
最后,要把你的网站部署到 GitHub Pages 上,请运行:
- Bash
- Windows
- PowerShell
GIT_USER=<GITHUB_USERNAME> yarn deploy