Posted on 2026-04-07 :: example

Cloudflare Pages

Cloudflare 是一家拥有庞大专有内容分发网络（CDN）的云解决方案提供商。与 Netlify 或 Vercel 类似，Cloudflare Pages 使部署过程变得灵活且简单。您可以将 GitHub 仓库添加到该服务中，并在每次提交拉取请求（PR）后自动构建并托管基于 Zola 的网站。

分步指南

登录或创建新的 Cloudflare 账户，并在右侧导航栏中选择“Pages”
点击“创建项目”按钮
选择包含您的 Zola 网站的 GitHub 仓库，并将其连接到 Cloudflare Pages
点击“开始设置”
输入您的项目名称。请注意，若您希望使用默认的 Pages 域名（pages.dev），这将成为您网站未来的 URL（"yourprojectname.pages.dev"）。此外，请选择一个生产分支。
在“构建设置”中，选择 Zola 作为框架预设。构建命令和构建输出目录将自动填充。
切换下方“环境变量”选项，并添加 ZOLA_VERSION 作为变量名。将 0.17.2 或其它 Zola 版本作为其值。
最后，保存并部署。

您的网站现已构建完成并部署到 Cloudflare 网络！您可以在 Pages 控制台中添加自定义域名或修改设置。

您可以在开发者门户中找到《Cloudflare Pages 入门》和《使用 Cloudflare Pages 部署 Zola》等文档和指南。

处理预览部署

在使用 Cloudflare Pages 时，您通常会通过预览部署来测试更改，然后将其合并到主分支。默认情况下，这些预览部署会使用不同的 URL（例如 https://your-branch-name.your-project.pages.dev），如果您的 config.toml 中硬编码了 base_url，这可能会导致资源加载问题。

要解决此问题，请修改 Cloudflare Pages 配置中的构建命令，根据环境动态设置基础 URL：

if [ "$CF_PAGES_BRANCH" = "main" ]; then zola build; else zola build --base-url $CF_PAGES_URL; fi

此命令：

从主分支构建时，使用 config.toml 中的 base_url
对于所有其他分支，使用预览部署 URL（由 Cloudflare Pages 自动提供，即 $CF_PAGES_URL）

故障排除

以下是一些有助于排查 Cloudflare Pages 入门问题的提示。

zola: not found

如果您看到类似以下的构建输出：

23:03:54.609    > build
23:03:54.609    > zola build $BUILD_OPTS && npx tailwindcss -i ./public/input.css -o ./public/style.css -m
23:03:54.609
23:03:54.621    sh: 1: zola: 未找到
23:03:54.635    失败：执行用户命令时出错。退出错误代码：127
23:03:54.644    失败：构建命令以代码 1 退出
23:03:55.699    失败：运行构建命令时发生错误

这可能是由于一个已知问题导致的。目前有两种推荐的解决方法：

将构建系统版本更改为 v1

在“Workers & Pages”仪表盘中，依次进入：设置 > 构建与部署 > 构建系统版本 > 配置构建系统

然后选择 v1 并保存。

或者使用 UNSTABLE_PRE_BUILD 环境变量 + asdf

在“Workers & Pages”仪表盘中，请执行以下操作：设置 > 环境变量 > 编辑变量

添加一个名为 UNSTABLE_PRE_BUILD 的环境变量，设置以下值，然后保存。

asdf plugin add zola https://github.com/salasrod/asdf-zola && asdf install zola latest && asdf global zola latest