Cloudflare Full Setup部署Astro

Astro 是高效的全栈框架，结合 Cloudflare 的边缘网络，能实现极速部署和全球加速。本文一步步指导你从零部署 Astro 项目到 Cloudflare，包括 Wrangler JSONC 配置、Pages 导入、域名设置、迁移策略、重定向优化及性能最佳实践。 docs.astro

wrangler-jsonc-配置区别

Static 模式（output: 'static'{type:""}）只需指定 assets 目录，无需适配器。

SSR/Hybrid 模式需安装 @astrojs/cloudflare{type:""}，添加 Worker 入口 main。 docs.astro

// wrangler.jsonc (Hybrid/SSR 示例)
{
  "$schema": "https://developers.cloudflare.com/workers/configuration/api.json",
  "name": "my-astro-site",
  "compatibility_date": "2026-02-05",
  "main": "dist/server/entry.js",
  "assets": { "directory": "./dist" }
}

运行 npx astro add cloudflare{type:""} 自动生成配置，本地预览 npx wrangler dev{type:""}。

pages-部署指南

仪表盘 > Workers & Pages > Create > Pages > Connect to Git，选择仓库授权。

构建设置：Framework preset 选 Astro，Build command npm run build{type:""}，Output directory dist。支持分支预览与自动 CI/CD。 logsnag

C3 CLI 新手首选：npx create-cloudflare@latest my-app --framework=astro{type:""}，一键安装依赖并部署。 developers.cloudflare

常见问题：构建失败多因 Node 版本（推荐 20+），在 Pages 设置中指定。

custom-domain-设置

Pages 项目 > Custom domains > Set up a domain，输入你的域名如 example.com。

• 子域名（www.example.com）：添加 CNAME 记录指向 <project>.pages.dev。
• Apex 域名（example.com）：切换域名 Nameservers 到 Cloudflare（如 ns1.cloudflare.com）。

启用 Proxy（橙色云图标）自动获 DDoS 保护、WAF 与智能缓存。SSL 选 Full (strict)，生效需 5-30 分钟。 docs.astro

缓存优化：在 public/_headers 添加：

/api/*
  Cache-Control: no-cache
/*
  Cache-Control: public, max-age=3600

服务商迁移策略

完整步骤：

1. 备份代码/数据，推送到 GitHub，新建 Pages 项目导入仓库。
2. 配置构建，部署后功能验证。
3. 更新域名 DNS 到 Cloudflare Nameservers，逐步分流流量（降低 TTL）。
4. 迁移服务：Netlify Functions → Workers，Vercel Edge → Cloudflare Workers，数据库 → D1/KV。
5. 清理旧资源，用 Analytics 监控（TTFB 通常降 30%+）。

Cloudflare 无限带宽 + 边缘计算，成本节省 50-80%。实战：Hugo/Netlify 迁移 Astro，用 _redirects 保留旧 URL。 developers.cloudflare

www-到-apex-重定向

Bulk Redirects（推荐）：Rules > Redirect Rules > Create：

• Source URL: https://www.example.com/*
• Target: https://example.com/${1}
• Status: 301 Permanent。

Astro 中间件（SSR/Hybrid）：

// src/middleware.ts
import { defineMiddleware } from 'astro:middleware';

export const onRequest = defineMiddleware((ctx, next) => {
  if (ctx.url.hostname === 'www.example.com') {
    return Response.redirect(`https://example.com${ctx.url.pathname}${ctx.url.search}`, 301);
  }
  return next();
});

静态站点：public/_redirects：

/www.example.com/*	https://example.com/:splat	301

优先级：Bulk > 中间件 > _redirects，确保 SEO Canonical 标签统一。 focusidler

speed-brain--prefetch-优化

Speed Brain：Cloudflare 预测预取工具（Chromium 121+），自动猜测高概率页面，仅预取缓存内容，LCP 平均降 40-45%，默认免费开启（Caching > Speed > Optimization > Speed Brain > On）。 blog.cloudflare

Astro 配置：

// astro.config.mjs
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server', // 或 hybrid
  adapter: cloudflare(),
  prefetch: {
    defaultStrategy: 'hover', // viewport/tap
    prefetchData: true
  }
});

链接添加 <a href="/next" data-astro-prefetch>，岛屿用 eagerness: 'eager'。

实战实践：

• 导航密集页全开，排除 /api/* /admin/* 避浪费。
• 结合 Image Optimization/Polish，堆叠加速。
• 测试：Lighthouse 预取覆盖 >70%，Analytics 监控命中率（典型 94%）。
• 案例：文档站 LCP 从 2.2s 优化至 1.1s。