从零搭建个人博客：Astro + Cloudflare 实战
用 Astro 写静态博客，推到 GitHub，由 Cloudflare 云端构建上线。含国内网络环境下的代理与依赖安装避坑。
这个博客用 Astro 写成静态站，推到 GitHub，由 Cloudflare 云端构建并托管。本文记录可复现的步骤，以及在国内网络环境下遇到的几个坑。整套方案不需要服务器，写完一篇 Markdown 推送即可自动上线。
技术选型
- Astro：把 Markdown 编译成静态 HTML，没有运行时负担，适合内容站。
- Cloudflare：托管静态资源，自带全球 CDN 和 HTTPS。
- 构建放在云端：本地只负责写作和
git push，npm install和打包都在 Cloudflare 的服务器上完成。
项目结构
src/
├─ pages/ # 每个文件对应一个页面
├─ layouts/ # 页面骨架与文章排版
├─ components/ # 头部、卡片、主题切换等
├─ content/blog/ # 所有文章（.md）
└─ styles/global.css # 设计系统：配色、字体、动画文章用 Astro 的内容集合管理，每篇顶部写一段 frontmatter：
---
title: 文章标题
description: 一句话摘要
pubDate: 2026-06-04
tags: ['标签一', '标签二']
---
正文用 Markdown 书写。推到 GitHub
git init
git add -A
git commit -m "init"
git branch -M main
git remote add origin https://github.com/<用户名>/blog.git
git push -u origin main源码放 GitHub 顺带解决备份：换机器或迁移时，git clone 即可。
在 Cloudflare 部署
入口是 Workers 和 Pages。新版后台把它放在「构建 → 计算」下，用顶部搜索框搜 Pages 最快。
注意：不要点进「Zero Trust」里的 Mesh，那是另一个功能，和静态托管无关。
点 创建应用程序 → 连接到 Git，授权并选中仓库。构建设置填：
- 构建命令：
npm run build - 部署命令：
npx wrangler deploy
走 Workers 静态资源托管，需要在仓库根放一个 wrangler.jsonc，声明这是纯静态站：
{
"name": "blog",
"compatibility_date": "2024-11-01",
"assets": {
"directory": "./dist",
"not_found_handling": "404-page"
}
}再加一个 .nvmrc，内容写 22，锁定云端 Node 版本，避免版本过旧导致构建失败。
点部署后，Cloudflare 拉取仓库、npm install、npm run build，再发布 dist/。整个过程在它的服务器上完成，约几十秒。
坑一：命令行连不上 GitHub
现象：浏览器能正常打开 GitHub，但 git push 超时或连接被重置。
原因：命令行默认不走系统代理。在本机代理的 fake-ip 模式下，git、curl 的直连请求被解析成无效地址（198.18.x.x），连接直接断开。
解决：给 git 显式指定代理端口（Clash 这类工具通常在 127.0.0.1 上开了混合端口，按实际填）。
git config --global http.proxy http://127.0.0.1:7897
git config --global https.proxy http://127.0.0.1:7897坑二：本地 npm install 卡死
现象：依赖下载到一半卡住，sharp 这类带预编译二进制的包尤其容易挂起。
原因：镜像 CDN 对单连接限速，实测单连接只有约 18 KB/s，而依赖总量上百 MB。
解决：优先不在本地构建，交给 Cloudflare（它的网络不受影响）。如果必须本地安装，提高并发并跳过可选依赖：
npm install --omit=optional --maxsockets=16 --prefer-offline限速是按单连接生效的，提高并发能成倍提升总吞吐。
绑定自定义域名
构建成功后会得到一个 *.workers.dev 的临时网址，先用它预览。要绑定自己的域名，最省事的方式是直接写进 wrangler.jsonc，由部署时自动创建，不用去后台点：
{
"name": "blog",
"compatibility_date": "2024-11-01",
"assets": { "directory": "./dist", "not_found_handling": "404-page" },
"routes": [
{ "pattern": "blog.must-xin.com", "custom_domain": true }
]
}推送后，云端的 wrangler deploy 会自动为这个域名创建路由、配好 DNS 和 TLS 证书（前提是域名托管在同一个 Cloudflare 账号下）。
一个坑：如果这个子域名此前已有冲突的 DNS 记录（比如曾经指向别的服务），wrangler deploy 会因为记录冲突而失败。这时先去 Cloudflare 后台把那条旧的 DNS 记录删掉，再重新部署即可。
日常写作
# 在 src/content/blog/ 下新建一个 .md，写好 frontmatter 和正文
git add .
git commit -m "post: 新文章"
git push推送后 Cloudflare 自动重新构建上线。不碰服务器，也不在本地打包。
核心就两点：内容用 Markdown 管理，构建交给云端。