部署
要为生产环境构建网站的静态文件,请运行:
- 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 页面不能做部署预览,至少方法非常复杂。 每个仓库只能和一个站点部署相关联。 另一方面,你还是可以控制哪些人有站点部署的写权限。
不存在通用方案。 你需要权衡你的需求和资源,然后再做决定。