BetterLink Logo 比邻
切换语言
切换主题

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

Cloudflare 全球网络节点与 Astro 框架部署示意图

引言

上周帮朋友部署 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 账号(没有的话注册一个,免费的)

具体步骤

  1. 登录 Cloudflare Dashboard 打开 dash.cloudflare.com,进入左侧菜单的 Workers & Pages

  2. 创建新项目 点击右上角 Create application → 选择 PagesConnect to Git

  3. 连接 GitHub 仓库 选择你的 Astro 项目仓库。第一次可能需要授权 Cloudflare 访问 GitHub,按提示操作就行。

  4. 配置构建设置 这一步很关键,填错了就部署失败。设置如下:

    • Framework preset:选择 Astro(会自动填充命令)
    • Build commandnpm run build
    • Build output directorydist
    • Root directory:如果项目在仓库根目录就留空,在子目录就填路径
  5. 点击部署Save and Deploy,等几分钟。Cloudflare 会自动拉代码、安装依赖、构建、部署。

构建成功后,你会得到一个 your-project.pages.dev 的域名,直接访问就能看到网站了。每次你推送代码到 GitHub,Cloudflare 会自动触发构建,超方便。

常见问题

  • 构建失败,提示 Node.js 版本不对:在项目根目录加个 .nvmrc 文件或者 .node-version,写上 1820。Cloudflare 会自动识别。
  • 页面显示 404:检查 Build output directory 是不是 dist。有些配置可能是 publicbuild,根据你的 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

这个命令会自动帮你做三件事:

  1. 安装 @astrojs/cloudflare
  2. 修改 astro.config.mjs 文件,添加适配器配置
  3. 创建 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 手动配置,稍微麻烦点。

常见错误排查

  1. “Hydration completed but contains mismatches” 这个错误挺常见的,原因是 Cloudflare 的 Auto Minify 功能把你的 HTML 压缩乱了。 解决方法:进入 Cloudflare Dashboard → 你的域名 → Speed → Optimization,把 Auto Minify 里的 HTML、CSS、JS 三个选项都关掉。

  2. “Cannot find module ‘MY_KV’” 说明绑定没配置好。检查 wrangler.jsonc 里的 binding 名称和代码里用的是否一致。

  3. 部署后页面 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 里配置。

步骤:

  1. 进入 Workers & Pages → 选择你的项目
  2. 点击 SettingsEnvironment Variables
  3. 点击 Add variable,输入名称和值
  4. 选择环境(Production 或 Preview)

敏感信息用 Secrets

对于特别敏感的数据(比如支付 API 密钥),用 Cloudflare 的 Secrets 功能,会加密存储:

npx wrangler secret put API_KEY

运行后会提示你输入值,不会显示在命令行里,更安全。

我的建议

  • 数据库 URL、第三方 API 密钥 → Secrets
  • 公开的配置(比如网站名称、CDN地址)→ 普通环境变量

国内访问速度优化实战

问题诊断:测试你的网站在国内的真实速度

部署完之后,先别急着优化,测一下实际速度再说。不是所有网站都需要优化,如果你的用户主要在国外,Cloudflare 默认配置就很完美了。

在线测速工具

  1. 17ce.com(推荐) 打开 17ce.com,输入你的域名,选择”网站速度测试”。会从国内不同省份、不同运营商测试。关注”响应时间”这一列,如果普遍在 200ms 以内,说明还不错;超过 300ms 就建议优化了。

  2. 站长工具 Ping 测试 tool.chinaz.com/speedtest,功能类似,可以看到更详细的路由信息。

本地测试

如果你自己在国内,可以用 Chrome 开发者工具测试:

  1. 按 F12 打开 DevTools
  2. 切换到 Network 选项卡
  3. 刷新页面,看第一个请求的 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 为例):

  1. 登录你的 DNS 服务商

  2. 找到你的域名,添加/修改 A 记录:

    • 主机记录:@(代表根域名)或 www
    • 记录类型:A
    • 记录值:104.16.160.10(你测出的优选IP)
    • TTL:600(10分钟)
  3. 保存,等待生效(一般5-10分钟)

步骤3:验证效果

DNS 生效后,再用 17ce.com 测一次速,应该能看到明显改善。

风险提示(重要!)

2025年1月,Cloudflare 更新了服务条款,里面有一条说可能会限制或处罚”滥用”行为。虽然没明确说优选IP 算不算,但存在风险。

我的建议

  • 个人博客、小项目:可以用,风险不大
  • 商业网站、流量大的项目:谨慎,建议用方案二(CNAME)或方案三(分地域解析)
  • 定期检查:IP 可能会失效,隔一两个月测一次,换新的

常见问题

  1. 改了 DNS 没生效

    • 清除浏览器缓存,或用无痕模式测试
    • 检查 DNS 是否真的生效了,用 nslookup yourdomain.com 命令查看
  2. 优选IP 一段时间后又慢了

    • IP 可能失效了,重新测速,换个新的
  3. 部分地区快,部分地区慢

    • 不同运营商(电信/联通/移动)最快的 IP 不一样,方案三(分地域解析)可以解决

方案二:使用优选 CNAME 域名(免费,更稳定)

如果你觉得自己测IP 太麻烦,或者担心 IP 经常失效,可以用公共的优选 CNAME 域名。这些域名背后是别人维护的优选IP,会定期更新,省心很多。

原理

有些开发者或组织会搭建一个域名,定期测试并解析到最新的优选IP。你只需要把你的域名 CNAME 到他们的域名,就能享受加速效果。

步骤1:选择公共 CNAME

常见的公共优选域名(这些只是示例,使用前请自己测试):

  • cdn.cloudflare.quest
  • cf.xiu2.xyz

注意:公共 CNAME 可能随时失效,建议加入相关社区或 Telegram 群,及时获取最新可用的域名。

步骤2:修改 DNS 解析

同样,域名 DNS 不能在 Cloudflare。配置方法(以 DNSPod 为例):

  1. 登录 DNS 服务商

  2. 添加 CNAME 记录:

    • 主机记录:@www
    • 记录类型:CNAME
    • 记录值:cdn.cloudflare.quest(你选的公共域名)
    • TTL:600
  3. 保存,等待生效

步骤3:解决可能的 403 错误

用 CNAME 方式容易遇到 403 Forbidden 错误,这是因为 Cloudflare 检测到你的域名没有在它的系统里注册,但又通过它的 IP 访问。

解决方法

  1. 把域名 DNS 从 Cloudflare 迁出(如果还在的话)
  2. 在 Cloudflare Dashboard 中删除该站点
  3. 等几分钟,再访问,应该就正常了

步骤4:验证效果

CNAME 生效后,用 nslookup yourdomain.com 查看是否解析到了公共 CNAME 域名,然后测速验证。

优缺点对比

  • 优点

    • 不用自己测IP,省事
    • 维护者会定期更新,稳定性更好
    • 风险比直接用优选IP 稍低
  • 缺点

    • 依赖第三方,他们停了你也没辙
    • 速度可能不如自己测的 IP(毕竟不是专门为你优化的)

我的建议:适合”想要优化但不想太折腾”的用户,性价比挺高的。

方案三:分地域解析(需付费 DNS,效果最佳)

这是终极方案,效果最好,但需要一点成本。适合国内外用户都多,对速度要求高的网站。

核心思路

针对不同地区的用户,返回不同的 IP 地址。比如:

  • 国内电信用户 → 解析到电信优选IP
  • 国内联通用户 → 解析到联通优选IP
  • 国外用户 → 解析到 Cloudflare 默认地址(或 your-project.pages.dev

这样所有人访问都是最优路径。

需要的工具

支持智能解析的 DNS 服务商,比如:

  • DNSPod(腾讯云旗下,个人版免费有基础功能)
  • 阿里云 DNS(收费,但功能强大)
  • Cloudflare DNS(不支持国内分线路,不适合这个场景)

配置方法(以 DNSPod 为例):

  1. 测试不同运营商的优选IP

    用 CloudflareSpeedTest 工具,分别在电信、联通、移动网络测试,记录最快的 IP。或者参考这些常用的 IP 段(自己测更准):

    • 电信:104.16.160.0/24
    • 联通:104.23.240.0/24
    • 移动:172.64.32.0/24
  2. 配置分线路解析

    登录 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
  3. 保存,等待生效

效果

分线路解析后,国内不同运营商的用户都能访问到最快的节点,国外用户走原生 Cloudflare,两边都照顾到。

成本

  • DNSPod 个人版:免费(支持基础分线路)
  • DNSPod 专业版:20元/月(支持更精细的分地域)
  • 阿里云 DNS:按查询量计费,小网站一个月几块钱

我的建议:如果你的网站月访问量>1万,值得投入这点成本,体验提升明显。

优化效果对比与监控

说了这么多方案,到底效果怎么样?我用实际数据对比一下。

优化前后速度对比(某博客实测,北京电信网络):

方案平均延迟TTFB加载时间成本
未优化(默认 Cloudflare)280ms1.8s3.2s免费
方案一:优选IP75ms0.5s1.1s免费
方案二:公共 CNAME120ms0.7s1.5s免费
方案三:分线路解析65ms0.4s0.9s20元/月

可以看到,优化后速度提升 3-5 倍,用户体验完全不一样。

长期监控方案

优化完不是结束,需要定期监控,因为 IP 可能失效。

推荐工具

  1. UptimeRobotuptimerobot.com

    • 免费监控 50 个站点
    • 每 5 分钟 ping 一次,宕机会发邮件通知
    • 可以看到响应时间趋势
  2. Cloudflare Analytics

    • 在 Cloudflare Dashboard 自带,免费
    • 查看访问来源、带宽使用、错误率
    • 缺点是看不到国内具体延迟
  3. Better Uptimebetteruptime.com

    • 付费,但有免费版
    • 可以创建公开的状态页,增加用户信任

何时需要调整优选IP

设置一个提醒,每 1-2 个月检查一次:

  1. 用 17ce.com 测速,看延迟是否明显变高
  2. 如果延迟>200ms,重新跑 CloudflareSpeedTest,换新IP
  3. 更新 DNS 记录

我自己的经验,IP 大概 2-3 个月会有一次明显波动,及时更换就行。

结论

说了这么多,总结一下核心要点。

部署流程方面,Cloudflare Pages 部署 Astro 真的很简单。纯静态站点,连接 GitHub 几分钟就搞定;需要 SSR 的话,用 npx astro add cloudflare 一键配置,选好 hybridserver 模式,该静态的静态、该动态的动态,灵活又高效。

SSR 配置方面,记住这几个关键点:

  • 90% 的场景用 hybrid 模式最合适
  • 需要 KV/D1/R2 就配置 wrangler.jsonc 绑定
  • 本地开发用 .dev.vars,生产环境在 Dashboard 配环境变量
  • 遇到 Hydration 错误,关掉 Auto Minify

国内访问优化方面,三个方案各有适用场景:

  • 方案一(优选IP):效果最好,免费,但需要定期维护,有一定风险
  • 方案二(公共 CNAME):省心,免费,效果中等,适合不想折腾的用户
  • 方案三(分线路解析):终极方案,需小额成本,国内外都照顾到

我的推荐

  • 个人博客、流量不大 → 方案一或方案二
  • 流量较大、重视体验 → 方案三
  • 商业项目 → 谨慎使用优选IP,优先考虑方案三或接受默认速度

下一步行动

如果你还没开始,现在就可以:

  1. 创建个 Cloudflare 账号,试试静态部署,感受一下速度
  2. 如果国内访问慢,先用 17ce.com 测一下,再决定是否优化
  3. 优化之后记得设个提醒,定期检查 IP 是否失效

进阶学习

部署只是第一步,Cloudflare 生态还有很多强大的功能:

  • Workers KV:键值存储,适合缓存、session
  • D1:SQLite 数据库,直接在边缘跑
  • R2:对象存储,对标 AWS S3,免费额度也很大
  • Pages Functions:在 Pages 里直接写无服务器函数

这些都能和 Astro 无缝集成,可以慢慢探索。

最后,如果这篇文章帮到了你,欢迎在评论区分享你的部署体验或者踩过的坑,大家一起交流学习。

发布于: 2025年12月3日 · 修改于: 2025年12月4日

相关文章