从 Astro 到 Cloudflare Pages:一次完整的个人博客部署记录
从 Astro 本地构建、GitHub 双仓库、私有文章合并,到 Cloudflare Pages、Deploy Hook 和腾讯云自定义域名的完整实战教程。
我一直希望拥有一个完全由自己控制的写作空间:界面可以定制,文章使用 Markdown 保存,代码可以公开,但未来文章不进入公开仓库。
本文记录了这个博客从本地开发、GitHub 管理、私有文章合并、Cloudflare Pages 部署,到腾讯云域名解析和 HTTPS 上线的完整过程,也包括实际遇到的问题和解决方式。
最终架构
最终方案由四部分组成:
公开代码仓库
colars/blog
│
├── Astro 页面与样式
├── 构建脚本
└── 少量公开文章
私有文章仓库
colars/blog-content
│
└── posts/*.md
Cloudflare Pages
│
├── 拉取公开代码
├── 使用只读 Token 拉取私有文章
├── 执行 pnpm build
└── 输出 dist
正式域名
blog.xieje.cn
这样公开代码可以被 Fork,但未来文章源码保存在私有仓库中,不会随公开仓库一起被 Fork。
需要明确的是:部署后的文章正文仍然是公开网页,可以被阅读、抓取和复制。这个方案保护的是文章源文件,不是内容访问权限。
一、技术栈和工具
本次使用的主要工具如下:
| 工具 | 用途 |
|---|---|
| Node.js 22+ | 运行 Astro、构建脚本和本地工具 |
| pnpm 11 | 安装依赖、执行构建命令 |
| Git | 管理公开代码和私有文章仓库 |
| Astro 7 | 生成静态博客 |
| TypeScript | 检查配置和脚本类型 |
| Tailwind CSS 4 | 页面样式 |
| Pagefind | 生成静态全文搜索索引 |
| GitHub | 保存代码和私有文章 |
| GitHub Actions | 在私有文章更新后触发部署 |
| Cloudflare Pages | 构建和托管静态站点 |
| Wrangler | 查看 Pages 项目、部署和 Secret |
| 腾讯云 DNSPod | 管理自定义域名 DNS |
本地开发时,先确认工具可用:
node --version
pnpm --version
git --version
项目要求的 Node.js 版本:
{
"engines": {
"node": ">=22.23.0"
}
}
Cloudflare Pages 构建环境中设置了:
NODE_VERSION=22
二、初始化 Astro 博客
项目目录:
D:\Project\Blog
安装依赖:
cd D:\Project\Blog
pnpm install
项目的主要依赖:
{
"dependencies": {
"@astrojs/rss": "^4.0.19",
"@astrojs/sitemap": "^3.7.4",
"@tailwindcss/vite": "^4.3.3",
"astro": "7.3.2",
"pagefind": "^1.5.2",
"tailwindcss": "^4.3.5"
}
}
主要目录:
src/
├─ components/ # 可复用页面组件
├─ config/ # 站点和作者配置
├─ content/posts/ # 公开文章
├─ layouts/ # 页面布局
├─ pages/ # Astro 路由
├─ styles/ # 全局样式
└─ utils/ # 内容和路由工具
常用的 package.json 脚本:
{
"scripts": {
"content:sync": "node scripts/sync-content.mjs",
"predev": "node scripts/sync-content.mjs",
"dev": "node scripts/astro.mjs dev",
"precheck": "node scripts/sync-content.mjs",
"check": "node scripts/astro.mjs check",
"prebuild": "node scripts/sync-content.mjs",
"build": "node scripts/astro.mjs build && pagefind --site dist",
"preview": "node scripts/astro.mjs preview"
}
}
predev、precheck 和 prebuild 会在主要命令执行前自动合并文章,避免忘记手动同步。
三、配置站点域名
站点地址在两个位置保持一致。
astro.config.mjs:
export default defineConfig({
site: "https://blog.xieje.cn",
integrations: [sitemap()],
});
src/config/site.ts:
export const siteConfig = {
title: "en 的个人随笔",
url: "https://blog.xieje.cn",
// ...
};
这两个地址会用于:
- canonical URL
- Open Graph 元信息
- RSS
- Sitemap
- 文章结构化数据
如果只修改其中一个,线上 SEO 地址很容易出现不一致。
四、文章格式
每篇文章使用 Markdown,文章头信息示例:
---
title: "文章标题"
description: "一句文章摘要"
publishedAt: 2026-11-17
category: "工程实践"
tags: ["Astro", "部署"]
cover: "/images/cover-blog.svg"
featured: false
draft: true
---
核心字段:
| 字段 | 作用 |
|---|---|
title |
文章标题 |
description |
摘要和 SEO 描述 |
publishedAt |
发布时间 |
category |
分类 |
tags |
标签 |
cover |
封面图 |
draft |
是否作为草稿排除 |
设置 draft: true 后,文章不会进入正式页面、RSS 和搜索索引。
五、公开文章与私有文章合并
公开文章保存在:
src/content/posts/
私有文章保存在另一个仓库:
colars/blog-content/
└─ posts/
├─ private-post.md
└─ images/
构建时,两类文章会合并到:
.content/posts/
该目录已加入 .gitignore:
.content/
.env
同步脚本会先复制公开文章,再复制私有文章:
await rm(outputPostsDir, { recursive: true, force: true });
await mkdir(outputPostsDir, { recursive: true });
await cp(publicPostsDir, outputPostsDir, { recursive: true });
私有仓库通过 GitHub API 下载:
const apiUrl =
`https://api.github.com/repos/${repository}/tarball/${encodeURIComponent(ref)}`;
const response = await fetch(apiUrl, {
headers: {
Accept: "application/vnd.github+json",
Authorization: `Bearer ${token}`,
"User-Agent": "en-personal-essays-build",
"X-GitHub-Api-Version": "2022-11-28",
},
redirect: "follow",
});
如果公开文章和私有文章存在同名文件,构建会直接终止:
Private content conflicts with an existing public file
这样不会静默覆盖已有文章。
六、创建 GitHub 公开代码仓库
初始化 Git:
cd D:\Project\Blog
git init -b main
git remote add origin https://github.com/colars/blog.git
如果目标仓库已经有 LICENSE 或其他初始提交,不要强推。先把远端历史安全拉下来:
git fetch origin main
git pull --ff-only origin main
提交前执行检查:
pnpm check
pnpm build
提交并推送:
git add -A
git commit -m "feat: 初始化 Astro 个人博客"
git push -u origin main
之后每次修改公开代码,都可以继续使用普通提交和普通推送,不使用 --force。
七、创建私有文章仓库
创建私有 GitHub 仓库:
colars/blog-content
克隆到本地:
git clone https://github.com/colars/blog-content.git D:\Project\BlogContent
cd D:\Project\BlogContent
创建文章目录:
New-Item -ItemType Directory posts -Force
New-Item -ItemType File posts\.gitkeep -Force
添加 .github/workflows/deploy-cloudflare-pages.yml:
name: Deploy Cloudflare Pages
on:
push:
paths:
- "posts/**"
workflow_dispatch:
permissions: {}
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Trigger Cloudflare Pages
env:
DEPLOY_HOOK_URL: ${{ secrets.CLOUDFLARE_DEPLOY_HOOK_URL }}
run: |
if [ -z "$DEPLOY_HOOK_URL" ]; then
echo "::error::Missing CLOUDFLARE_DEPLOY_HOOK_URL repository secret."
exit 1
fi
curl --fail --silent --show-error --request POST "$DEPLOY_HOOK_URL"
提交并推送:
git add .
git commit -m "chore: 初始化私有文章目录与部署工作流"
git push -u origin main
这个工作流只发送部署请求,不下载文章,也不会把文章复制到公开仓库。
八、创建只读 GitHub Token
在 GitHub 创建 Fine-grained personal access token。
配置:
Resource owner: colars
Repository access: Only select repositories
Repository: colars/blog-content
Contents: Read-only
Metadata: Read-only
Expiration: 180 days
只读 Token 不代表永久有效。账号权限变化、Token 过期、仓库被转移或 Token 被撤销后,都需要重新生成。
Token 只保存到 Cloudflare Pages 的加密环境变量中,不写入:
.env.example- README
- Git 提交
- 构建日志
- 截图
九、配置 Cloudflare Pages
在 Cloudflare 中创建 Pages 项目:
Project name: en-blog-pages
Git provider: GitHub
Repository: colars/blog
Production branch: main
Framework preset: Astro
Build command: pnpm build
Build output directory: dist
Root directory: 留空
添加环境变量:
BLOG_CONTENT_REPO=colars/blog-content
BLOG_CONTENT_REF=main
CONTENT_REPO_TOKEN=<180 天只读 Token>
NODE_VERSION=22
其中 CONTENT_REPO_TOKEN 必须保存为 Cloudflare Secret,而不是普通明文变量。
构建命令只需要:
pnpm build
因为 prebuild 会自动执行:
node scripts/sync-content.mjs
成功的构建日志应该包含:
[content] Merged 0 private post(s) from colars/blog-content@main.
[content] Ready with 3 total post(s).
私有仓库暂时没有文章时,合并数量为 0 是正常的。
十、创建 Deploy Hook
Cloudflare Pages 的 Git 集成只监听公开代码仓库。私有文章仓库更新时,需要额外的 Deploy Hook。
在 Cloudflare:
Workers & Pages
→ en-blog-pages
→ Settings
→ Builds & deployments
→ Deploy hooks
→ Add
配置:
Name: blog-content-main
Branch: main
保存生成的 URL。这个 URL 本身相当于敏感凭据,不能公开。
在私有仓库添加 Actions Secret:
Settings
→ Secrets and variables
→ Actions
→ New repository secret
名称:
CLOUDFLARE_DEPLOY_HOOK_URL
也可以使用 GitHub CLI:
gh secret set CLOUDFLARE_DEPLOY_HOOK_URL `
--repo colars/blog-content
命令会提示输入 Secret 值,不要把 Deploy Hook URL 直接写进 YAML 文件。
测试工作流:
gh workflow run deploy-cloudflare-pages.yml `
--repo colars/blog-content `
--ref main
查看执行结果:
gh run list --repo colars/blog-content
gh run watch <run-id> --repo colars/blog-content --exit-status
GitHub Actions 成功后,Cloudflare 会重新拉取公开代码和私有文章并部署。
十一、配置腾讯云自定义域名
Cloudflare Pages 子域名绑定流程必须按正确顺序执行:
- 先在 Cloudflare Pages 添加自定义域名。
- 再到腾讯云 DNSPod 添加 CNAME。
Cloudflare 中进入:
Workers & Pages
→ en-blog-pages
→ Custom domains
→ Set up a domain
填写:
blog.xieje.cn
然后在腾讯云 DNSPod 添加记录:
| 字段 | 值 |
|---|---|
| 主机记录 | blog |
| 记录类型 | CNAME |
| 线路类型 | 默认 |
| 记录值 | en-blog-pages.pages.dev |
| TTL | 600 |
记录值不要带:
https://
也不要在末尾添加 /。
回到 Cloudflare Custom domains 页面,等待状态变成:
Active
Cloudflare Pages 会自动签发 HTTPS 证书,不需要在腾讯云额外申请 SSL 证书。
十二、验证部署
检查 DNS:
Resolve-DnsName blog.xieje.cn
检查首页:
Invoke-WebRequest https://blog.xieje.cn/ -UseBasicParsing |
Select-Object StatusCode
检查 canonical:
$response = Invoke-WebRequest `
https://blog.xieje.cn/ `
-UseBasicParsing
[regex]::Match(
$response.Content,
'<link rel="canonical" href="([^"]+)"'
).Groups[1].Value
预期结果:
https://blog.xieje.cn/
检查 RSS、Sitemap 和搜索:
Invoke-WebRequest https://blog.xieje.cn/rss.xml -UseBasicParsing
Invoke-WebRequest https://blog.xieje.cn/sitemap-0.xml -UseBasicParsing
Invoke-WebRequest https://blog.xieje.cn/search/ -UseBasicParsing
Invoke-WebRequest https://blog.xieje.cn/pagefind/pagefind-ui.js -UseBasicParsing
Pagefind 搜索索引只在生产构建后生成。开发模式主要验证布局和写作流程,完整搜索需要使用:
pnpm build
pnpm preview
十三、实际遇到的问题
1. pnpm 忽略了 esbuild 构建脚本
构建前出现过:
ERR_PNPM_IGNORED_BUILDS
Ignored build scripts: esbuild
解决方式是只在项目中允许 esbuild:
pnpm-workspace.yaml:
allowBuilds:
esbuild: true
然后重新安装:
pnpm install
2. Git 提示目录所有权异常
不同 Windows 账户访问同一个仓库时可能出现:
detected dubious ownership
确认目录确实属于自己后,可以添加安全目录:
git config --global --add safe.directory D:/Project/Blog
如果只是临时检查,也可以对单次命令使用:
git -c safe.directory=D:/Project/Blog status
3. 目标 GitHub 仓库不是空的
目标仓库原本已经有一个 LICENSE 初始提交。
错误做法是直接强推,因为它会覆盖远端历史。
正确方式:
git fetch origin main
git pull --ff-only origin main
确认远端文件后再提交本地代码。
4. 创建成了 Worker 而不是 Pages
Cloudflare Dashboard 中的 Workers 和 Pages 入口容易混淆。
检查 Pages 项目:
pnpm dlx wrangler pages project list --json
如果列表为空,但下面命令能找到项目:
pnpm dlx wrangler deployments list --name en-blog
说明创建的是 Worker,不是 Pages。
本项目最终使用的 Pages 项目是:
en-blog-pages
5. 私有仓库拉取返回 404
Cloudflare 构建日志:
Unable to download private content repository (404).
GitHub 对“没有私有仓库权限的 Token”通常返回 404,而不是 403。
需要检查:
- Fine-grained Token 是否选择了
colars/blog-content - 是否授予
Contents: Read-only - Token 是否过期或被撤销
- 资源所有者是否为
colars - Cloudflare 中的 Token 是否复制完整
6. Token 被保存成普通文本
Cloudflare Pages 环境变量有不同存储类型。CONTENT_REPO_TOKEN 应使用加密 Secret。
如果保存成普通文本,Dashboard 中能看到原值,存在泄露风险。
可以将 Secret 统一设置为:
secret_text
7. 私有文章更新不会自动触发 Cloudflare
Cloudflare Git 集成只监听公开代码仓库。
因此额外增加了:
私有文章仓库 push
→ GitHub Actions
→ Cloudflare Deploy Hook
Deploy Hook 必须创建在 Git 集成的 Pages 项目中,Direct Upload 项目不能按这个方式工作。
8. 先加 CNAME 导致 522
如果还没有在 Pages 项目中关联自定义域名,就先添加了 CNAME,访问可能返回:
522 Connection timed out
解决顺序必须是:
Cloudflare 添加自定义域名
→ 腾讯云添加 CNAME
→ 等待证书和域名状态 Active
9. pages.dev 地址仍然存在
绑定自定义域名后,原来的:
https://en-blog-pages.pages.dev
不会自动消失。
因此需要同步修改 canonical、RSS 和 Sitemap 的正式域名。如果要强制旧地址跳转,可以后续使用 Cloudflare Bulk Redirect。
10. 搜索页在开发模式下没有结果
Pagefind 依赖生产构建生成的索引文件。
开发时只运行:
pnpm dev
搜索索引可能不可用。
完整验证方式:
pnpm build
pnpm preview
十四、安全边界
当前方案需要注意以下事项:
- 只读 Token 仍有有效期,180 天后需要轮换。
- Deploy Hook URL 不能公开,只保存在私有仓库 Actions Secret 中。
CONTENT_REPO_TOKEN必须使用 Cloudflare Secret。.content/和.env不提交到 Git。- 私有文章仓库不能设置成公开仓库。
- 部署后的文章正文是公开 HTML,不能阻止读者复制。
- 如果文章曾经进入公开 Git 历史,仅删除当前文件并不等于从历史中移除。
十五、最终验证清单
上线后逐项检查:
- 首页返回 200
- 文章详情页可以访问
- 归档、标签和分类正常
- canonical 使用正式域名
- RSS 使用正式域名
- Sitemap 使用正式域名
- Pagefind 搜索资源返回 200
- 私有文章可以合并进入构建
- 私有文章推送后 Deploy Hook 成功触发
- GitHub Actions 工作流执行成功
- Cloudflare Pages 最新部署状态为 Active
- Token 保存为加密 Secret
- 公开仓库中没有新增私有文章源码
pnpm check为 0 错误pnpm build成功生成dist
最终站点:
参考资料
- Astro 官方文档
- Astro Cloudflare Pages 部署指南
- Cloudflare Pages Git integration
- Cloudflare Pages Build configuration
- Cloudflare Pages Deploy Hooks
- Cloudflare Pages Custom domains
- Cloudflare Wrangler 文档
- Pagefind 文档
- GitHub Actions Secrets
- GitHub Fine-grained personal access tokens
- 腾讯云 DNSPod 解析记录文档
- Firefly Astro 博客主题