Astro Cloudflare部署完全指南:SSR配置+国内访问3倍提速

引言
上周帮朋友部署 Astro 博客,遇到了个挺有意思的问题。网站部署到 Cloudflare Pages 之后,我在国外测试,页面秒开,体验超级流畅。结果他国内的朋友打开一看,转了快5秒才加载出来,这就尴尬了。
明明 Cloudflare 号称全球300多个数据中心,免费还不限带宽,为什么国内访问这么慢呢?其实这个问题困扰了很多开发者。你可能也听说过”优选IP”这个词,但具体怎么操作、会不会被封号、效果到底怎么样,心里总是打鼓。
这篇文章我会带你完整走一遍 Astro Cloudflare 部署流程,从最基础的静态站点到 SSR 配置,再到国内访问优化。说实话,我自己踩了不少坑,现在把经验整理出来,希望能帮你少走弯路。
你会学到:
- 20分钟完成从零到部署上线
- 搞懂 SSR 适配器的三种模式,不再纠结
- 掌握3种国内访问优化方案,延迟降低3倍
话不多说,直接开始。
为什么选择 Cloudflare Pages
Cloudflare vs Vercel:免费托管平台对比
经常有人问我,Vercel 和 Cloudflare 到底选哪个?说白了,看你的需求。
带宽限制差异最明显。Vercel 免费计划每月100GB带宽,超出后按量计费,每 100GB 要 $40。我之前有个项目突然上了热榜,流量暴涨,结果收到 Vercel 的账单,心疼了好一阵子。Cloudflare Pages 呢?无限带宽,完全免费。这对个人开发者来说真的太友好了,再也不用担心流量爆了被收费。
全球性能方面,Cloudflare 有300多个数据中心,覆盖更广。我在欧洲、亚洲、美洲测了几个点,延迟都挺低的。Vercel 的边缘网络也不错,但节点数量相对少一些。如果你的用户分布在全球各地,Cloudflare 的优势更明显。
还有个很实在的优点:DDoS 防护。Cloudflare 的免费计划就自带 DDoS 保护,不用额外配置。之前网站被攻击,Cloudflare 自动拦截了,我连日志都没看到。Vercel 也有防护,但免费版的防护主要是保护他们自己的网络,不是专门给你的站点做深度防护。
那 Vercel 有什么优势呢?构建缓存做得很好。如果你的项目图片多、依赖多,Vercel 会保留上次构建的缓存,第二次构建只需要3-4分钟。Cloudflare Pages 每次都是从头构建,十几分钟起步。还有就是 Next.js 的深度集成,如果你用 Next.js,Vercel 确实是最佳选择,毕竟是亲儿子。
我的建议:
- Astro 静态博客 → Cloudflare Pages(免费流量大)
- 流量不可预测的项目 → Cloudflare Pages(避免被收费)
- Next.js 深度用户 → Vercel(体验最好)
- 需要快速迭代、构建频繁 → Vercel(构建缓存快)
Cloudflare Pages vs Workers:2025年新变化
这个问题我一开始也挺困惑的。Cloudflare 既有 Pages 又有 Workers,都能部署 Astro,到底用哪个?
本质区别其实挺简单。Workers 是 Cloudflare 的无服务器计算平台,你可以在边缘跑 JavaScript 代码。Pages 呢,可以理解为 Workers + 自动化构建工具的封装。Pages 底层还是用 Workers 运行,但提供了 Git 集成、自动部署这些开箱即用的功能。
2025年的新变化是,Cloudflare 官方开始推荐新项目用 Workers 而不是 Pages。我翻了翻官方博客,主要原因是 Workers 更灵活、控制更精细。不过对咱们 Astro 用户来说,这个建议不用太较真。
我的实际体验:
- Pages 方式:连接 GitHub 仓库,推送代码自动触发构建,简单粗暴。适合”我就想快速部署,别搞复杂了”的场景。
- Workers 方式:需要用 Wrangler CLI 手动部署,配置 wrangler.jsonc 文件。好处是可以更精细地控制环境变量、绑定 KV 存储等。
那 Astro 项目该选哪个?
- 纯静态站点(output: ‘static’):用 Pages,通过 Dashboard 连接 GitHub 最方便
- SSR 站点(output: ‘server’ 或 ‘hybrid’):两个都行,但我更推荐用 Pages + Wrangler CLI 部署,既有自动化又有灵活性
说白了,如果你是第一次部署,先用 Pages 的 Git 集成试试水,几分钟就能看到效果。等熟悉了再考虑 Wrangler CLI,不急。
Astro Cloudflare 部署完整流程
静态站点部署:5分钟快速上手
如果你的 Astro 项目是纯静态的(博客、文档站、作品集这类),部署真的超级简单。我按步骤带你走一遍。
前提条件:
- 项目已经推送到 GitHub
- 有 Cloudflare 账号(没有的话注册一个,免费的)
具体步骤:
登录 Cloudflare Dashboard 打开 dash.cloudflare.com,进入左侧菜单的 Workers & Pages。
创建新项目 点击右上角 Create application → 选择 Pages → Connect to Git。
连接 GitHub 仓库 选择你的 Astro 项目仓库。第一次可能需要授权 Cloudflare 访问 GitHub,按提示操作就行。
配置构建设置 这一步很关键,填错了就部署失败。设置如下:
- Framework preset:选择 Astro(会自动填充命令)
- Build command:
npm run build - Build output directory:
dist - Root directory:如果项目在仓库根目录就留空,在子目录就填路径
点击部署 点 Save and Deploy,等几分钟。Cloudflare 会自动拉代码、安装依赖、构建、部署。
构建成功后,你会得到一个 your-project.pages.dev 的域名,直接访问就能看到网站了。每次你推送代码到 GitHub,Cloudflare 会自动触发构建,超方便。
常见问题:
- 构建失败,提示 Node.js 版本不对:在项目根目录加个
.nvmrc文件或者.node-version,写上18或20。Cloudflare 会自动识别。 - 页面显示 404:检查
Build output directory是不是dist。有些配置可能是public或build,根据你的astro.config.mjs调整。 - 构建超时:可能是依赖太多或网络问题,重新部署试试,一般第二次就好了。
绑定自定义域名(可选):
部署成功后,在项目设置里找到 Custom domains,点 Set up a custom domain,输入你的域名(比如 blog.yourdomain.com)。Cloudflare 会给你一个 CNAME 记录,去你的 DNS 服务商那里添加就行。如果域名本身就在 Cloudflare DNS,会自动配置,更简单。
SSR 站点部署:@astrojs/cloudflare 适配器配置详解
SSR 这块我一开始也挺懵的,官方文档写得挺分散。这里我按实际操作顺序,把每一步都说清楚。
什么时候需要 SSR?
先说清楚场景,免得你不确定要不要用:
- 需要实时数据:比如评论区、访问统计、用户登录这些
- 需要服务器端逻辑:API 调用、数据库查询、权限验证
- 需要按需渲染:内容量巨大,不想全部预渲染成静态页面
如果你就是个纯博客,文章都是 Markdown 文件,完全不需要 SSR,用静态部署就行。
步骤1:安装 @astrojs/cloudflare 适配器
在项目根目录运行:
npx astro add cloudflare这个命令会自动帮你做三件事:
- 安装
@astrojs/cloudflare包 - 修改
astro.config.mjs文件,添加适配器配置 - 创建
wrangler.jsonc文件(Cloudflare Workers 的配置文件)
运行完之后,你的 astro.config.mjs 大概长这样:
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';
export default defineConfig({
output: 'server', // 这行是新加的
adapter: cloudflare(),
});步骤2:选择渲染模式(重点!)
这里有三个选项,很多人就卡在这里了。我详细解释一下:
1. output: 'server' - 全站 SSR
- 所有页面都在服务器端渲染
- 适合:数据驱动的应用,需要频繁更新的内容
- 缺点:每次请求都要渲染,性能稍慢
2. output: 'hybrid' - 混合模式(推荐)
- 默认所有页面是静态的
- 特定页面可以选择 SSR
- 适合:大部分页面是静态的博客,但有少量动态功能
- 优点:灵活性最高,性能最好
3. output: 'static' - 纯静态
- 不需要适配器,就是前面说的静态部署
我的建议:90% 的情况选 hybrid,除非你确定全站都需要 SSR。
hybrid 模式使用示例:
// astro.config.mjs
export default defineConfig({
output: 'hybrid', // 改成 hybrid
adapter: cloudflare(),
});然后在需要 SSR 的页面里,加一行:
// src/pages/api/comments.js
export const prerender = false; // 这个页面会 SSR
export async function GET() {
// 从数据库获取评论
const comments = await fetchComments();
return new Response(JSON.stringify(comments));
}其他页面默认还是静态的,不用动。
步骤3:配置 Cloudflare 服务绑定(可选)
如果你需要用到 Cloudflare 的 KV 存储、D1 数据库、R2 对象存储,需要在 wrangler.jsonc 里配置绑定。
举个例子,我想用 KV 存储保存用户 session:
// wrangler.jsonc
{
"name": "my-astro-app",
"compatibility_date": "2024-01-01",
"kv_namespaces": [
{
"binding": "MY_KV",
"id": "your-kv-namespace-id"
}
]
}你需要先在 Cloudflare Dashboard 里创建一个 KV namespace,复制 ID 填进去。
然后在代码里这样用:
// src/pages/api/session.js
export const prerender = false;
export async function GET({ locals }) {
const { MY_KV } = locals.runtime.env;
const sessionData = await MY_KV.get('user:123');
return new Response(sessionData);
}步骤4:本地开发和测试
安装 Wrangler CLI(Cloudflare 官方工具):
npm install wrangler --save-dev本地运行:
npm run build
npx wrangler pages dev ./dist这样会启动一个本地服务器,模拟 Cloudflare 环境,可以测试 SSR 功能和绑定是否正常。
步骤5:部署上线
有两种方式:
方式1:通过 Wrangler CLI 部署(推荐,控制更精细)
# 登录 Cloudflare 账号
npx wrangler login
# 构建项目
npm run build
# 部署
npx wrangler pages deploy ./dist第一次部署会让你输入项目名称,之后就是一行命令搞定。
方式2:通过 Git 集成自动部署
还是用前面静态部署的方式,连接 GitHub 仓库,Cloudflare 会自动识别 @astrojs/cloudflare 适配器。不过这种方式绑定 KV 等服务需要在 Dashboard 手动配置,稍微麻烦点。
常见错误排查:
“Hydration completed but contains mismatches” 这个错误挺常见的,原因是 Cloudflare 的 Auto Minify 功能把你的 HTML 压缩乱了。 解决方法:进入 Cloudflare Dashboard → 你的域名 → Speed → Optimization,把 Auto Minify 里的 HTML、CSS、JS 三个选项都关掉。
“Cannot find module ‘MY_KV’” 说明绑定没配置好。检查
wrangler.jsonc里的binding名称和代码里用的是否一致。部署后页面 500 错误 查看 Cloudflare Dashboard → Workers & Pages → 你的项目 → Logs(实时日志),看具体报错信息。大概率是代码里访问了未绑定的资源。
环境变量和密钥管理
环境变量这块很多人搞混,我之前也把 API 密钥不小心推到 GitHub 了,后来赶紧撤回。这里说说正确姿势。
本地开发环境:
在项目根目录创建 .dev.vars 文件(注意前面有个点):
# .dev.vars
DATABASE_URL=postgres://localhost:5432/mydb
API_KEY=your-secret-key-for-dev重要:把 .dev.vars 加到 .gitignore 里,别推到 GitHub!
本地开发时,Wrangler 会自动读取这个文件。你在代码里这样访问:
export const prerender = false;
export async function GET({ locals }) {
const apiKey = locals.runtime.env.API_KEY;
// 使用 apiKey 调用第三方 API
}生产环境:
不要用 .dev.vars,而是在 Cloudflare Dashboard 里配置。
步骤:
- 进入 Workers & Pages → 选择你的项目
- 点击 Settings → Environment Variables
- 点击 Add variable,输入名称和值
- 选择环境(Production 或 Preview)
敏感信息用 Secrets:
对于特别敏感的数据(比如支付 API 密钥),用 Cloudflare 的 Secrets 功能,会加密存储:
npx wrangler secret put API_KEY运行后会提示你输入值,不会显示在命令行里,更安全。
我的建议:
- 数据库 URL、第三方 API 密钥 → Secrets
- 公开的配置(比如网站名称、CDN地址)→ 普通环境变量
国内访问速度优化实战
问题诊断:测试你的网站在国内的真实速度
部署完之后,先别急着优化,测一下实际速度再说。不是所有网站都需要优化,如果你的用户主要在国外,Cloudflare 默认配置就很完美了。
在线测速工具:
17ce.com(推荐) 打开 17ce.com,输入你的域名,选择”网站速度测试”。会从国内不同省份、不同运营商测试。关注”响应时间”这一列,如果普遍在 200ms 以内,说明还不错;超过 300ms 就建议优化了。
站长工具 Ping 测试 tool.chinaz.com/speedtest,功能类似,可以看到更详细的路由信息。
本地测试:
如果你自己在国内,可以用 Chrome 开发者工具测试:
- 按 F12 打开 DevTools
- 切换到 Network 选项卡
- 刷新页面,看第一个请求的 Time 值
判断标准:
- 延迟 < 150ms:很好,不用优化
- 延迟 150-250ms:还行,看个人需求
- 延迟 > 250ms 或 加载时间 > 3 秒:建议优化
为什么国内会慢?
简单说,Cloudflare 用的是 Anycast 技术,国内网络环境特殊,路由经常绕远路。比如你在北京访问,流量可能先绕到香港再回来,延迟自然高。优选IP/CNAME 的原理就是找那些路由更直接的节点。
方案一:使用优选IP(免费,效果最好)
这是效果最明显的方案,我自己测试过,延迟从 280ms 降到 70ms 左右。不过需要动手能力稍强一点,而且有点风险,后面会说。
什么是优选IP?
Cloudflare 有几百个 IP 地址,不同 IP 对应不同的数据中心。国内访问这些 IP 的速度差异很大,有的绕远路慢得要死,有的直连快如闪电。优选IP 就是找出那些快的 IP,让你的域名直接解析到它们。
步骤1:测试优选IP
用 CloudflareSpeedTest 这个工具,GitHub 上下载:XIU2/CloudflareSpeedTest
Windows 用户下载 CloudflareST.exe,Linux/Mac 下载对应版本。
运行方法(Windows):
# 双击运行或命令行执行
CloudflareST.exe工具会自动测试几百个 Cloudflare IP,大概需要 5-10 分钟。完成后会输出最快的 IP 列表,比如:
IP地址 延迟 下载速度
104.16.160.10 68ms 15.2MB/s
172.64.32.5 75ms 14.8MB/s
104.23.240.28 82ms 13.9MB/s记下第一个 IP(延迟最低的)。
步骤2:修改 DNS 解析
重要前提:你的域名 DNS 不能托管在 Cloudflare,必须是其他服务商(阿里云、DNSPod、Cloudflare 之外的)。如果当前在 Cloudflare DNS,需要先转出。
为什么?因为 Cloudflare DNS 会强制走 Anycast,你改 A 记录也没用。
配置方法(以 DNSPod 为例):
登录你的 DNS 服务商
找到你的域名,添加/修改 A 记录:
- 主机记录:
@(代表根域名)或www - 记录类型:A
- 记录值:
104.16.160.10(你测出的优选IP) - TTL:600(10分钟)
- 主机记录:
保存,等待生效(一般5-10分钟)
步骤3:验证效果
DNS 生效后,再用 17ce.com 测一次速,应该能看到明显改善。
风险提示(重要!):
2025年1月,Cloudflare 更新了服务条款,里面有一条说可能会限制或处罚”滥用”行为。虽然没明确说优选IP 算不算,但存在风险。
我的建议:
- 个人博客、小项目:可以用,风险不大
- 商业网站、流量大的项目:谨慎,建议用方案二(CNAME)或方案三(分地域解析)
- 定期检查:IP 可能会失效,隔一两个月测一次,换新的
常见问题:
改了 DNS 没生效
- 清除浏览器缓存,或用无痕模式测试
- 检查 DNS 是否真的生效了,用
nslookup yourdomain.com命令查看
优选IP 一段时间后又慢了
- IP 可能失效了,重新测速,换个新的
部分地区快,部分地区慢
- 不同运营商(电信/联通/移动)最快的 IP 不一样,方案三(分地域解析)可以解决
方案二:使用优选 CNAME 域名(免费,更稳定)
如果你觉得自己测IP 太麻烦,或者担心 IP 经常失效,可以用公共的优选 CNAME 域名。这些域名背后是别人维护的优选IP,会定期更新,省心很多。
原理:
有些开发者或组织会搭建一个域名,定期测试并解析到最新的优选IP。你只需要把你的域名 CNAME 到他们的域名,就能享受加速效果。
步骤1:选择公共 CNAME
常见的公共优选域名(这些只是示例,使用前请自己测试):
cdn.cloudflare.questcf.xiu2.xyz
注意:公共 CNAME 可能随时失效,建议加入相关社区或 Telegram 群,及时获取最新可用的域名。
步骤2:修改 DNS 解析
同样,域名 DNS 不能在 Cloudflare。配置方法(以 DNSPod 为例):
登录 DNS 服务商
添加 CNAME 记录:
- 主机记录:
@或www - 记录类型:CNAME
- 记录值:
cdn.cloudflare.quest(你选的公共域名) - TTL:600
- 主机记录:
保存,等待生效
步骤3:解决可能的 403 错误
用 CNAME 方式容易遇到 403 Forbidden 错误,这是因为 Cloudflare 检测到你的域名没有在它的系统里注册,但又通过它的 IP 访问。
解决方法:
- 把域名 DNS 从 Cloudflare 迁出(如果还在的话)
- 在 Cloudflare Dashboard 中删除该站点
- 等几分钟,再访问,应该就正常了
步骤4:验证效果
CNAME 生效后,用 nslookup yourdomain.com 查看是否解析到了公共 CNAME 域名,然后测速验证。
优缺点对比:
优点:
- 不用自己测IP,省事
- 维护者会定期更新,稳定性更好
- 风险比直接用优选IP 稍低
缺点:
- 依赖第三方,他们停了你也没辙
- 速度可能不如自己测的 IP(毕竟不是专门为你优化的)
我的建议:适合”想要优化但不想太折腾”的用户,性价比挺高的。
方案三:分地域解析(需付费 DNS,效果最佳)
这是终极方案,效果最好,但需要一点成本。适合国内外用户都多,对速度要求高的网站。
核心思路:
针对不同地区的用户,返回不同的 IP 地址。比如:
- 国内电信用户 → 解析到电信优选IP
- 国内联通用户 → 解析到联通优选IP
- 国外用户 → 解析到 Cloudflare 默认地址(或
your-project.pages.dev)
这样所有人访问都是最优路径。
需要的工具:
支持智能解析的 DNS 服务商,比如:
- DNSPod(腾讯云旗下,个人版免费有基础功能)
- 阿里云 DNS(收费,但功能强大)
- Cloudflare DNS(不支持国内分线路,不适合这个场景)
配置方法(以 DNSPod 为例):
测试不同运营商的优选IP
用 CloudflareSpeedTest 工具,分别在电信、联通、移动网络测试,记录最快的 IP。或者参考这些常用的 IP 段(自己测更准):
- 电信:104.16.160.0/24
- 联通:104.23.240.0/24
- 移动:172.64.32.0/24
配置分线路解析
登录 DNSPod,添加多条 A 记录,每条设置不同的”线路类型”:
记录1: - 主机记录:@ - 记录类型:A - 线路类型:电信 - 记录值:104.16.160.10 记录2: - 主机记录:@ - 记录类型:A - 线路类型:联通 - 记录值:104.23.240.5 记录3: - 主机记录:@ - 记录类型:A - 线路类型:移动 - 记录值:172.64.32.8 记录4(默认线路,给国外用户): - 主机记录:@ - 记录类型:CNAME - 线路类型:默认 - 记录值:your-project.pages.dev保存,等待生效
效果:
分线路解析后,国内不同运营商的用户都能访问到最快的节点,国外用户走原生 Cloudflare,两边都照顾到。
成本:
- DNSPod 个人版:免费(支持基础分线路)
- DNSPod 专业版:20元/月(支持更精细的分地域)
- 阿里云 DNS:按查询量计费,小网站一个月几块钱
我的建议:如果你的网站月访问量>1万,值得投入这点成本,体验提升明显。
优化效果对比与监控
说了这么多方案,到底效果怎么样?我用实际数据对比一下。
优化前后速度对比(某博客实测,北京电信网络):
| 方案 | 平均延迟 | TTFB | 加载时间 | 成本 |
|---|---|---|---|---|
| 未优化(默认 Cloudflare) | 280ms | 1.8s | 3.2s | 免费 |
| 方案一:优选IP | 75ms | 0.5s | 1.1s | 免费 |
| 方案二:公共 CNAME | 120ms | 0.7s | 1.5s | 免费 |
| 方案三:分线路解析 | 65ms | 0.4s | 0.9s | 20元/月 |
可以看到,优化后速度提升 3-5 倍,用户体验完全不一样。
长期监控方案:
优化完不是结束,需要定期监控,因为 IP 可能失效。
推荐工具:
UptimeRobot(uptimerobot.com)
- 免费监控 50 个站点
- 每 5 分钟 ping 一次,宕机会发邮件通知
- 可以看到响应时间趋势
Cloudflare Analytics
- 在 Cloudflare Dashboard 自带,免费
- 查看访问来源、带宽使用、错误率
- 缺点是看不到国内具体延迟
Better Uptime(betteruptime.com)
- 付费,但有免费版
- 可以创建公开的状态页,增加用户信任
何时需要调整优选IP:
设置一个提醒,每 1-2 个月检查一次:
- 用 17ce.com 测速,看延迟是否明显变高
- 如果延迟>200ms,重新跑 CloudflareSpeedTest,换新IP
- 更新 DNS 记录
我自己的经验,IP 大概 2-3 个月会有一次明显波动,及时更换就行。
结论
说了这么多,总结一下核心要点。
部署流程方面,Cloudflare Pages 部署 Astro 真的很简单。纯静态站点,连接 GitHub 几分钟就搞定;需要 SSR 的话,用 npx astro add cloudflare 一键配置,选好 hybrid 或 server 模式,该静态的静态、该动态的动态,灵活又高效。
SSR 配置方面,记住这几个关键点:
- 90% 的场景用
hybrid模式最合适 - 需要 KV/D1/R2 就配置
wrangler.jsonc绑定 - 本地开发用
.dev.vars,生产环境在 Dashboard 配环境变量 - 遇到 Hydration 错误,关掉 Auto Minify
国内访问优化方面,三个方案各有适用场景:
- 方案一(优选IP):效果最好,免费,但需要定期维护,有一定风险
- 方案二(公共 CNAME):省心,免费,效果中等,适合不想折腾的用户
- 方案三(分线路解析):终极方案,需小额成本,国内外都照顾到
我的推荐:
- 个人博客、流量不大 → 方案一或方案二
- 流量较大、重视体验 → 方案三
- 商业项目 → 谨慎使用优选IP,优先考虑方案三或接受默认速度
下一步行动:
如果你还没开始,现在就可以:
- 创建个 Cloudflare 账号,试试静态部署,感受一下速度
- 如果国内访问慢,先用 17ce.com 测一下,再决定是否优化
- 优化之后记得设个提醒,定期检查 IP 是否失效
进阶学习:
部署只是第一步,Cloudflare 生态还有很多强大的功能:
- Workers KV:键值存储,适合缓存、session
- D1:SQLite 数据库,直接在边缘跑
- R2:对象存储,对标 AWS S3,免费额度也很大
- Pages Functions:在 Pages 里直接写无服务器函数
这些都能和 Astro 无缝集成,可以慢慢探索。
最后,如果这篇文章帮到了你,欢迎在评论区分享你的部署体验或者踩过的坑,大家一起交流学习。
发布于: 2025年12月3日 · 修改于: 2025年12月4日


