部署到 Cloudflare Pages

约 715 字大约 2 分钟

2026-08-31

Cloudflare Pages 提供全球 CDN、免费 SSL 与不限请求数的静态资源分发，是个人博客性价比很高的选择。

前置条件

重要

Node.js 环境变量设置 Cloudflare Pages 默认构建镜像的 Node 版本较旧。必须在环境变量中添加 NODE_VERSION = 22，以满足 Node.js ≥ 22.12 的运行要求。

登录 Cloudflare Dashboard，进入 Workers & Pages → Create → Pages → Connect to Git。
选择 Git 提供商并授权，选中你的 Shirone 仓库。
配置构建设置：
配置项值
Project name 自定义（决定默认域名 <name>.pages.dev）
Production branch main
Build command pnpm build
Build output directory dist
展开 Environment variables，添加 NODE_VERSION = 22（满足 Node.js ≥ 22.12 的要求）。
务必添加此变量： Cloudflare 构建镜像默认的 Node 版本低于 22，缺少此变量时构建必然失败。
点击 Save and Deploy，首次构建约 3-6 分钟。

此后推送 main 触发生产部署，推送其他分支自动生成预览部署（<hash>.<name>.pages.dev）。

适合本地构建后交付产物，无需授权 Git 仓库：

pnpm add -g wrangler

wrangler login
pnpm build
wrangler pages deploy dist --project-name=shirone-blog

提示

CLI 部署跳过了平台构建环节，本地执行 pnpm build 时 Pagefind 索引与字体子集化都已包含在产物中，上传即可获得完整功能。

进入项目 Custom domains → Set up a custom domain，输入域名。
若域名已托管在同一 Cloudflare 账号，DNS 记录自动添加；否则按提示去域名服务商添加 CNAME 记录指向 <name>.pages.dev。
SSL 证书自动签发，通常数分钟内生效。

Cloudflare 默认策略对静态站点已足够合理：HTML 短缓存、指纹化资源长缓存。如需精细控制，在 public/ 下添加 _headers 文件：

public/_headers
/assets/*
  Cache-Control: public, max-age=31536000, immutable

/pagefind/*
  Cache-Control: public, max-age=86400

构建失败：Unsupported engine 或语法错误

国内访问速度

500 次构建额度

版权归属：matsuzaka-yuki