部署到 Cloudflare Pages

纯静态站，Cloudflare Pages 免费套餐足够，唯一开销是域名年费。

一、推仓库

bash

git init
git add .
git commit -m "init: vitepress site"
git branch -M main
git remote add origin https://github.com/your-name/personal-site.git
# ssh连接 git remote add origin git@gitee.com:your-name/personal-site.git
git push -u origin main

二、在 Pages 建项目

Cloudflare 控制台 Build-Compute→ Workers & Pages → Create → Pages → Connect to Git

底下 Need to use the legacy Pages workflow? Continue to Pages

→ Import an existing Git repository

选中仓库，然后填构建参数：仓库需要github 或gitlab；不支持gitee

参数	值
Framework preset	VitePress
Build command	`npm run docs:build`
Build output directory	`docs/.vitepress/dist`
环境变量	`NODE_VERSION` = `20`

NODE_VERSION 该填就填，Cloudflare 默认的 Node 版本可能偏低，不指定容易构建失败。

首次部署完会得到一个 xxx.pages.dev 的免费域名，能直接访问。

三、绑自己的域名

可直接免费用Cloudflare 的子域名，Cloudfare 里的 Project name 就是域名主体，自己设置

域名在阿里云/腾讯云/Namecheap 等任意注册商买，.top 首年便宜，续费约 30 元/年
把域名的 NS 记录改成 Cloudflare 分配的两个地址（在 Cloudflare 添加站点后会给）
回到 Pages 项目 → Custom domains → 输入域名 → 激活
等 DNS 生效，几分钟到几小时，HTTPS 证书由 Cloudflare 自动签发

只绑子域名也行

如果不想把整个域名的 NS 交给 Cloudflare，可以只在原注册商加一条 CNAME：www → xxx.pages.dev，然后只绑 www 子域名。

四、两种更新方式

Git 集成：git push 自动触发构建，带每次部署的历史，可回滚
手动上传：npx wrangler pages deploy docs/.vitepress/dist，适合本地改完不想提交

五、常见报错

现象	原因	处理
构建失败 `Node version not supported`	默认 Node 太低	加环境变量 `NODE_VERSION=20`
全站 404 / CSS 丢失	`base` 配错	独立域名保持默认 `/`
点链接变成下载 `.html`	未开 `cleanUrls`	本文项目已开，无需处理
部署成功但页面是旧的	浏览器/CDN 缓存	强制刷新或清 Cloudflare 缓存
中文路径乱码	终端编码	文件名用英文，标题用中文

部署到 Cloudflare Pages ​

一、推仓库 ​

二、在 Pages 建项目 ​

三、绑自己的域名 ​