背景
我想托管一个用 Astro 搭建的轻量个人博客。博客源代码已存储在 GitHub 仓库中，目标很简单：
- 将源代码保存在 GitHub
- 让 Cloudflare 自动构建网站
- 避免手动上传本地构建文件
- 使用简洁的
pages.dev域名，而不是workers.dev域名 - 不将
node_modules或生成的构建输出提交到仓库，保持仓库整洁
最初，我将网站部署为 Cloudflare Worker。虽然可以运行，但默认 URL 看起来是这样的：
https://victorbi.spearfishingchina.workers.dev/这不是我想要的博客形式。我希望使用 Cloudflare Pages 项目，因为 Pages 的默认 URL 更简洁：
https://victorbi.pages.dev/项目结构
我的 Astro 项目位于仓库的 src 目录下。
重要的结构如下：
repo-root/
├── README.md
├── deploy/
│ └── cloudflare/
│ └── website/
│ └── ...
└── src/
├── package.json
├── pnpm-lock.yaml
├── astro.config.ts
├── public/
└── src/
├── content/
├── pages/
├── layouts/
└── components/deploy/cloudflare/website/ 目录包含已构建的静态文件，例如：
index.html
404.html
_astro/
pagefind/
rss.xml
sitemap-index.xml该目录可用于测试，但并不适合作为 Cloudflare Pages 的长期来源。更好的做法是让 Cloudflare 直接从 Astro 源代码构建网站。
为什么更换部署方式
部署静态 Astro 博客有两种方式：
方式一：本地构建后上传静态文件
即在本地机器上运行构建，然后上传生成的文件。
例如：
cd src
pnpm run build然后手动上传生成的 dist 文件夹。
这种方式可行，但并不理想，因为每次更新都需要手动操作。
方式二：让 Cloudflare 从 GitHub 构建
这是更好的长期方案。
工作流变为：
撰写博客文章
提交到 GitHub
推送到 GitHub
Cloudflare Pages 构建 Astro 网站
Cloudflare Pages 部署生成的 dist 文件夹这种方式更简洁，因为 GitHub 存储源代码，Cloudflare 自动处理构建和部署。
清理仓库
仓库不应跟踪生成的文件或本地依赖。
我添加或更新了根目录的 .gitignore 文件：
node_modules/
src/node_modules/
dist/
src/dist/
deploy/cloudflare/website/
.wrangler/
.dev.vars
.env然后从 Git 跟踪中移除生成文件，但不删除本地文件：
git rm -r --cached src/node_modules || true
git rm -r --cached deploy/cloudflare/website || true
git rm -r --cached src/dist || true
git rm -r --cached dist || true之后提交清理内容：
git add .gitignore
git commit -m "Clean up generated files for Cloudflare Pages deployment"
git push检查 Astro 构建脚本
在 src/package.json 中，我确认其中包含构建脚本。
重要部分如下：
{
"scripts": {
"build": "astro build"
}
}对于我的项目，Cloudflare Pages 只需要运行构建命令。Astro 默认会将静态网站生成到 dist 目录。
本地测试构建
在配置 Cloudflare 之前，我先在本地测试了构建。
cd src
pnpm install
pnpm run build构建成功后，Astro 生成了：
src/dist/该 dist 文件夹即为最终的静态网站。
其中包含以下文件：
index.html
404.html
_astro/
posts/
tags/
rss.xml
sitemap-index.xml找到 Cloudflare Pages 选项
在 Cloudflare 控制台中，我进入：
Workers & Pages
→ 创建应用令人困惑的是，主页面首先显示的是 Worker 选项，例如：
Continue with GitHub
Connect GitLab
Start with Hello World!
Select a template
Upload your static files这些选项会创建 Worker 应用。
Pages 的正确入口在底部：
Looking to deploy Pages? Get started我点击了那里的 Get started。
创建 Cloudflare Pages 项目
进入 Pages 设置后，我选择了：
导入现有 Git 仓库然后连接了我的 GitHub 仓库。
Cloudflare Pages 构建设置
我使用了以下 Pages 配置：
项目名称：
victorbi
生产分支：
main
框架预设：
Astro
根目录：
src
构建命令：
pnpm run build
构建输出目录：
dist重要细节如下：
根目录 = src
构建输出目录 = dist由于我的 Astro 项目位于仓库的 src 文件夹内，Cloudflare 必须从该目录运行构建。
因此 Cloudflare 识别的项目结构如下：
repo-root/src/package.json
repo-root/src/astro.config.ts
repo-root/src/pnpm-lock.yaml构建完成后，Astro 将网站输出到：
repo-root/src/dist从 Cloudflare Pages 的角度来看，由于根目录已设置为 src，输出目录只需填写：
dist而不是：
src/dist设置 Node 版本
我还添加了一个构建环境变量：
NODE_VERSION = 22这可以保持构建环境稳定，避免现代 Astro 版本出现 Node 版本兼容问题。
部署网站
保存 Cloudflare Pages 配置后，我触发了第一次部署。
预期流程为：
Cloudflare 拉取 GitHub 仓库
Cloudflare 进入 src 目录
Cloudflare 安装依赖
Cloudflare 运行 pnpm run build
Astro 生成 dist 文件夹
Cloudflare Pages 部署 dist 文件夹部署完成后，网站可通过 Pages URL 访问：
https://victorbi.pages.dev/Worker 与 Pages 的区别
我最初创建的是 Worker 部署，生成的 URL 如下：
https://victorbi.spearfishingchina.workers.dev/这是因为 Worker 使用以下默认 URL 格式：
worker-name.account-subdomain.workers.dev对于博客来说，这不是我想要的形式。
Cloudflare Workers 可以托管静态网站，但对于简单的 Astro 博客，Cloudflare Pages 更为自然。Pages 提供更简洁的默认域名和更直观的心智模型：
GitHub 仓库
→ Cloudflare Pages 构建
→ 静态网站最终配置
我的最终配置如下：
源代码：
GitHub
托管：
Cloudflare Pages
框架：
Astro
包管理器：
pnpm
项目根目录：
src
构建命令：
pnpm run build
输出目录：
dist
Node 版本：
22最终工作流
现在发布工作流非常简单：
cd src
pnpm run build如果本地构建成功，我撰写或编辑博客文章后直接推送更改：
git add .
git commit -m "Add new blog post"
git pushCloudflare Pages 会自动构建并部署更新后的博客。
给未来自己的备注
不要提交以下文件夹：
node_modules/
src/node_modules/
dist/
src/dist/
deploy/cloudflare/website/不要将旧的本地构建输出文件夹作为 Cloudflare 项目根目录。
正确的 Cloudflare Pages 项目根目录为：
src正确的 Cloudflare Pages 构建输出目录为：
dist这意味着 Cloudflare 从源代码构建，并自动部署生成的 Astro 静态网站。