部署到 Cloudflare Pages

本页介绍将本站部署到 Cloudflare Pages 的完整流程，包括部署配置、两种部署方式、SPA 回退规则以及部署后的检查与域名配置。

本站托管于 Cloudflare Pages，部署配置位于 wrangler.toml：

name = "keqing1120"                       # Cloudflare Pages 项目名（换成你的）
pages_build_output_dir = "dist"           # 发布目录：npm run build 的产物目录
compatibility_date = "2026-06-30"         # Pages 兼容性日期

字段	说明
name	Cloudflare Pages 项目名，全局唯一。换成你自己的项目名
pages_build_output_dir	发布目录。本项目构建产物在 dist/（vite build + 预渲染的结果），不要改
compatibility_date	Cloudflare 运行时的兼容性日期，一般保持不动

部署方式

方式一：Git 集成（推荐）

1. 将代码推送到 GitHub 仓库
2. Cloudflare 控制台 → Workers & Pages → 创建项目 → Pages → 连接你的 Git 仓库
3. 构建设置：

   设置项	值
   框架预设	无 / Vite
   构建命令	npm run build
   输出目录	dist
   Node 版本	18 或更高（环境变量 NODE_VERSION=18）

4. 保存并部署。此后每次 git push 都会自动构建并上线

注意

Cloudflare Pages 的构建容器默认未安装 Chromium。如构建日志报预渲染失败，将构建命令改为：

npx playwright install chromium && npm run build

方式二：Wrangler CLI 本地构建后上传

npm run build                    # 本地完成构建 + 预渲染
npx wrangler pages deploy dist   # 上传 dist/

适用于不接入 Git，或需要在发布前人工验收的场景。

SPA 回退

public/_redirects 内容：

/*    /index.html   200

作用：直接访问或刷新 /contributors 等客户端路由时，返回 index.html 并由 React Router 接管。Cloudflare Pages 原生支持 _redirects 文件，无需额外配置。

迁移到其它平台时的等价配置：

平台	配置方式
Nginx	try_files $uri $uri/ /index.html;
Vercel	vercel.json 中 "rewrites": [{ "source": "/(.*)", "destination": "/index.html" }]
Netlify	_redirects 文件语法相同

另外，预渲染已生成 dist/contributors/index.html，即使回退失效，直接访问该路径仍可获取静态内容；但其它新增路由仍依赖回退规则。

部署后检查清单

• [ ] 首页与 /contributors 直接访问（不经过首页跳转）均正常
• [ ] 浅色 / 深色模式切换正常
• [ ] 音乐可播放、图片完整
• [ ] 查看部署后页面的网页源代码能看到完整内容（预渲染生效）
• [ ] https://你的域名/sitemap.xml 与 /robots.txt 可访问
• [ ] 手机浏览器访问正常，粒子动画流畅

域名与 SEO

• 在 Cloudflare Pages 项目的「自定义域」中绑定域名（可使用 Cloudflare DNS 一键接入）
• 部署后，将 index.html 中的 og:url、canonical 以及 public/sitemap.xml 中的域名替换为正式域名，见 改造成你的网站