你可以告知 Cloudflare Pages 如何构建站点以及输出文件的位置。
应提供构建命令以告知 Cloudflare Pages 如何构建应用。对于未列出的项目,请阅读工具或框架的文档,并提交 pull request 将其添加到此列表。
构建目录表示项目构建命令输出 Cloudflare Pages 站点构建版本的位置。通常默认为行业标准的 public,但你可能需要自定义。
了解构建配置
构建命令由框架提供。例如,Gatsby 框架使用 gatsby build 作为构建命令。未使用框架时,将 Build command(构建命令) 字段留空。Pages 通过读取用户提供的构建命令返回的退出码来判断构建是否成功。任何非零返回码都会将构建标记为失败。退出码为 0 时,Pages 构建将标记为成功并上传资源,无论是否有错误日志写入标准错误。
构建目录由构建命令生成。每个框架有自己的命名约定,例如许多框架的构建输出目录名为 /public。
根目录是站点内容所在的位置。若未指定,Cloudflare 假定关联的 git 仓库为根目录。在 monorepo 等情况下需要指定根目录,此时一个仓库中可能有多个项目。
Cloudflare 维护流行框架和工具的构建配置列表。这些配置在项目创建时可用。以下是流行框架和工具的一些标准构建命令和目录。
如果不使用预设,请使用 exit 0 作为 Build command(构建命令)。
| 框架/工具 | 构建命令 | 构建目录 |
|---|---|---|
| React (Vite) | npm run build | dist |
| Gatsby | npx gatsby build | public |
| Next.js | npx @cloudflare/next-on-pages@1 | .vercel/output/static |
| Next.js (Static HTML Export) | npx next build | out |
| Nuxt.js | npm run build | dist |
| Qwik | npm run build | dist |
| Remix | npm run build | build/client |
| Svelte | npm run build | public |
| SvelteKit | npm run build | .svelte-kit/cloudflare |
| Vue | npm run build | dist |
| Analog | npm run build | dist/analog/public |
| Astro | npm run build | dist |
| Angular | npm run build | dist/cloudflare |
| Brunch | npx brunch build --production | public |
| Docusaurus | npm run build | build |
| Elder.js | npm run build | public |
| Eleventy | npx @11ty/eleventy | _site |
| Ember.js | npx ember-cli build | dist |
| GitBook | npx gitbook-cli build | _book |
| Gridsome | npx gridsome build | dist |
| Hugo | hugo | public |
| Jekyll | jekyll build | _site |
| MkDocs | mkdocs build | site |
| Pelican | pelican content | output |
| React Static | react-static build | dist |
| Slate | ./deploy.sh | build |
| Umi | npx umi build | dist |
| VitePress | npx vitepress build | .vitepress/dist |
| Zola | zola build | public |
如果项目使用环境变量来构建站点,你可以提供自定义环境变量:
-
在 Cloudflare 仪表板中,前往 Workers & Pages 页面。
前往 Workers & Pages ↗ -
选择你的 Pages 项目。
-
选择 Settings(设置) > Environment variables(环境变量)。
以下系统环境变量默认注入(但可以被覆盖):
| 环境变量 | 注入的值 | 使用场景示例 |
|---|---|---|
CI |
true |
在 CI 上运行时与本地运行时更改构建行为 |
CF_PAGES |
1 |
调整在 Pages 上运行与在本地运行时的构建行为 |
CF_PAGES_COMMIT_SHA |
<sha1-hash-of-current-commit> |
将当前提交 ID 传递给错误报告,例如 Sentry |
CF_PAGES_BRANCH |
<branch-name-of-current-deployment> |
根据分支自定义构建,例如在 production 上禁用调试日志 |
CF_PAGES_URL |
<url-of-current-deployment> |
让构建工具获知页面将部署到的 URL |