把静态博客部署到 Cloudflare Pages
Cloudflare Pages 对静态站点几乎是最省事的托管方案:免费额度够用、全球边缘节点、支持自定义域名和自动 HTTPS,而且不会像某些平台那样在页面里插入广告或跳转页。
下面三种方式,按"从简单到工程化"排列,选一种就够。
方式一:直接上传 dist 目录
最快的方式,不需要 Git,不需要命令行。
- 登录 Cloudflare Dashboard,进入 Workers & Pages
- 点 Create → Pages → Upload assets
- 把项目名填上,例如
my-blog - 把本地
dist目录整个拖进去,点 Deploy - 几十秒后拿到
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 preset | None |
| Build command | npm run build |
| Build output directory | dist |
| Node version | 20 或更高(环境变量 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, immutable4. 构建产物把源码一起传上去了
dist 里只应该有最终文件。如果把 content/、node_modules/ 也复制进去,部署体积会翻好几倍,而且别人可以直接下载你的草稿。
验证清单
上线后花两分钟检查这几项:
- 首页、文章页、标签页都能打开
/rss.xml、/sitemap.xml返回的是 XML 而不是 404- 手机上看一遍排版
- 在 PageSpeed Insights 跑一次,静态站通常能到 95 分以上
做完这些,就可以安心写下一篇文章了。