使用cloudflare-page部署digital-biome
使用 Cloudflare Pages 部署静态站点的完整流程与注意事项
[!info] related notes
使用 Cloudflare Pages 部署 digital-biome
目标
使用 Cloudflare Pages 部署静态站点（如 Astro、Hugo、Vite 等构建的网站），享受免费托管、全球 CDN 和自动部署。
前置条件
- GitHub / GitLab 账号，且项目代码已推送到远程仓库
- Cloudflare 账号（免费即可）
- 项目使用静态站点生成器（Astro、Hugo、Next.js SSG 等）或纯 HTML
步骤
1. 连接仓库
- 登录 Cloudflare Dashboard
- 左侧菜单 → Workers & Pages
- 点击 Create application → Pages → Connect to Git
- 授权 Cloudflare 访问你的 GitHub/GitLab
- 选择要部署的仓库
[!warning] 子仓库使用 HTTP 地址 如果项目中引用了 Git 子模块（submodule），子仓库必须使用 HTTP 地址而非 SSH。否则 Cloudflare Pages 拉取时没有权限，会导致构建失败。
2. 构建配置
| 设置项 | 示例值（Astro 项目） |
|---|---|
| Production branch | main |
| Build command | npm run build |
| Build output directory | dist |
常见框架的构建输出目录：
- Astro:
dist - Hugo:
public - Vite / Vue / React:
dist - Next.js SSG:
out - Gatsby:
public
3. 环境变量
在项目的 Pages 设置中添加环境变量：
NODE_VERSION：设为18或20（默认可能太旧）NODE_ENV：production- 其他项目需要的环境变量（如 API key）
4. 自定义域名
- 在 Pages 项目设置中点击 Custom domains
- 输入你的域名（如
digital-biome.example.com） - 按提示添加 DNS 记录（CNAME 指向
xxx.pages.dev） - Cloudflare 会自动配置 SSL 证书
5. 触发部署
- 推送到 Production 分支会自动触发构建和部署
- Pull Request 会生成预览 URL（Preview deployment）
Cloudflare Pages 入口
[!tip] Pages 入口在底部 Cloudflare Dashboard 的导航栏中，Workers & Pages 在左侧菜单底部，容易被忽略。
验证
- Cloudflare Pages 项目页面显示最近一次部署状态为
Success - 访问
xxx.pages.dev能看到网站内容 - 自定义域名解析正常，HTTPS 证书有效
- Push 代码后自动触发重新部署
- PR 生成了预览链接
常见问题
Q: 构建失败，提示 “Build output directory not found”？
A: 检查 Build output directory 设置是否与框架的输出目录一致。Astro 是 dist 而非 build。
Q: 部署成功但访问 404？
A: 检查构建输出目录是否正确，以及项目根目录下是否有 index.html。SPA 项目可能需要配置 _redirects 或 _headers 文件。
Q: 子模块拉取失败？
A: 将子模块 URL 从 SSH（git@github.com:...）改为 HTTPS（https://github.com/...）。在 .gitmodules 中修改。
Q: 环境变量不生效？
A: Cloudflare Pages 的环境变量在构建时注入，需要在 Pages 项目设置中添加（而非 .env 文件）。构建后变量不会暴露给客户端（除非以 PUBLIC_ 前缀命名）。
Q: 如何回滚到之前的部署？ A: 在 Pages 项目的 Deployments 页面，找到想回滚的版本，点击右侧菜单 → Rollback to this deployment。