把静态博客部署到 Cloudflare Pages

Cloudflare Pages 对静态站点几乎是最省事的托管方案:免费额度够用、全球边缘节点、支持自定义域名和自动 HTTPS,而且不会像某些平台那样在页面里插入广告或跳转页。

下面三种方式,按"从简单到工程化"排列,选一种就够。

方式一:直接上传 dist 目录

最快的方式,不需要 Git,不需要命令行。

  1. 登录 Cloudflare Dashboard,进入 Workers & Pages
  2. 点 Create → Pages → Upload assets
  3. 把项目名填上,例如 my-blog
  4. 把本地 dist 目录整个拖进去,点 Deploy
  5. 几十秒后拿到 my-blog.pages.dev

适合第一次上线验证效果。缺点是每次改文章都要手动重传。

方式二:命令行部署

装一次 Wrangler,之后一条命令发布:

npm i -D wrangler
npx wrangler pages deploy dist --project-name my-blog

第一次执行会打开浏览器让你授权登录 Cloudflare 账号。之后如果想在 CI 里跑,改用 API Token:

export CLOUDFLARE_API_TOKEN=你的token
export CLOUDFLARE_ACCOUNT_ID=你的account_id
npx wrangler pages deploy dist --project-name my-blog --branch main

建议把 token 存在环境变量或 CI 的 Secrets 里,不要写进仓库。Token 权限只需要 Cloudflare Pages: Edit。

方式三:连 GitHub 自动构建

最省心的长期方案。把仓库推到 GitHub,然后在 Pages 里选 Connect to Git:

配置项填写内容
Framework presetNone
Build commandnpm run build
Build output directorydist
Node version20 或更高(环境变量 NODE_VERSION=20)

之后每次 push 都会自动构建部署,PR 还会生成独立的预览地址,方便先看效果再合并。

自定义域名

在 Pages 项目的 Custom domains 里添加域名。两种情况:

  • 域名也托管在 Cloudflare:一条 CNAME 自动配好,等证书签发即可
  • 域名在别处:按提示添加 CNAME 记录指向 my-blog.pages.dev,注意不要在中间再加一层代理,否则证书验证可能卡住

证书签发通常几分钟,偶尔要等十几分钟。别在证书还没签发完的时候反复删除重加,这会让排队重新开始。

几个容易踩的坑

1. 忘记改 siteUrl

blog.config.mjs 里的 siteUrl 如果还是占位地址,RSS、sitemap、canonical 全是错的,搜索引擎抓到的链接会指向 pages.dev。上线第一件事就是改它,然后重新构建。

2. 404 没有生效

Cloudflare Pages 会自动把 dist/404.html 当作 404 页,但只在文件位于输出目录根部时有效。如果它被放在子目录里,访问不存在的路径会得到一个空白页。

3. 缓存了旧的 HTML

Pages 对 HTML 默认不设长缓存,一般不会出问题。但如果你在 _headers 里给 /* 加了 max-age=31536000,改动就会迟迟不生效。正确做法是只给静态资源设长缓存:

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

4. 构建产物把源码一起传上去了

dist 里只应该有最终文件。如果把 content/、node_modules/ 也复制进去,部署体积会翻好几倍,而且别人可以直接下载你的草稿。

验证清单

上线后花两分钟检查这几项:

  1. 首页、文章页、标签页都能打开
  2. /rss.xml、/sitemap.xml 返回的是 XML 而不是 404
  3. 手机上看一遍排版
  4. 在 PageSpeed Insights 跑一次,静态站通常能到 95 分以上

做完这些,就可以安心写下一篇文章了。