部署到主流平台：Vercel/Netlify/Cloudflare

第 50 章讲了部署的全局概念。这一章落到具体平台，挑最常用的三家：Vercel、Netlify、Cloudflare。它们对 Astro 支持都很好，但部署姿势略有不同。

共通步骤：三家都一样的部分

不管选哪家，下面这条主线三家通用：

1. 装适配器。用官方一键命令，装包并自动改 astro.config.mjs：

   npx astro add vercel     # Vercel
   npx astro add netlify    # Netlify
   npx astro add cloudflare # Cloudflare

2. 设 output。静态站点用默认 static 即可；要 SSR 就设 output: 'server' 或 'hybrid'（适配器装好后通常已帮你处理好相关配置）。

3. 构建。本地或平台云端执行 astro build，产物在 dist/。

4. 部署。把产物交给平台。

第 1 步的 astro add 是关键：它不只是 npm install，还会把适配器写进配置、必要时创建平台所需的配置文件（比如 Cloudflare 的 wrangler.jsonc）。所以优先用 astro add，别手动装完忘了改配置。

还有一个容易忘的全局配置：astro.config 里的 site 字段。它告诉 Astro 你站点的正式域名，SSR 下生成绝对 URL、以及 RSS、sitemap（站点地图）、规范化链接都依赖它。如果部署后链接错乱、图片 404，先回头确认 site 填的是线上真实域名，而不是本地的 localhost。静态站点不配 site 大多也能跑，但配上更稳妥，尤其当你用到第 47、48 章的 SEO 与 RSS 产出时。

Vercel：零配置，最省心

Vercel 对 Astro 是「零配置」友好。静态站点默认就能部署，不需要任何额外配置。

要启用按需渲染，装 Vercel 适配器：

npx astro add vercel

装好即用。部署有两种方式：

方式一：网站界面（UI）。

1. 把代码推到 Git 仓库（GitHub / GitLab / Bitbucket）。
2. 在 Vercel 导入这个仓库。
3. Vercel 会自动识别 Astro，配好构建设置。
4. 点 Deploy，得到如 astro.vercel.app 的地址。

之后每次推送到主分支，Vercel 自动重建并发布；其他分支会生成预览部署。

方式二：CLI。

npm install -g vercel
vercel

Vercel 同样自动识别 Astro。当问 Want to override the settings? [y/N] 时选 N 即可。

如果需要更细的控制（比如给响应加 HTTP 头），可以用 vercel.json 覆盖默认行为。整体而言，Vercel 是最「推上去就完事」的选择。

Netlify：静态/SSR/边缘三种形态

Netlify 支持三种部署形态：静态站点、SSR 站点、边缘渲染（edge）站点。静态站点默认即可，无需额外配置。

启用按需渲染：

npx astro add netlify

部署同样有 UI 和 CLI 两条路。

UI 部署：

1. Netlify 控制台点 Add a new site → Import an existing project。
2. 导入 Git 仓库后，Netlify 会自动识别并预填配置。
3. 确认构建命令 astro build、发布目录 dist，点 Deploy。

你也可以在项目根建一个 netlify.toml 固化这些设置：

[build]
  command = "npm run build"
  publish = "dist"

CLI 部署：

npm install --global netlify-cli
netlify login
netlify init

CLI 会自动检测构建命令和发布目录，并提议生成 netlify.toml。之后 git push 就会触发自动重建。

一个小提醒：如果用的是 Netlify 旧构建镜像，记得设 Node.js 版本（v22.12.0 以上），可以用 .nvmrc 文件或控制台的 NODE_VERSION 环境变量指定。另外，Netlify Functions 开箱即用，在根目录建 netlify/functions 即可。

Cloudflare：用 Wrangler 部署

Cloudflare 的部署和其他两家有个明显区别：它依赖 Wrangler（Cloudflare 的命令行工具）来部署，而不是单纯连 Git 自动发布（当然它也支持 CI/CD，后面会说）。

静态站点可以直接用 Wrangler 托管 dist/ 下的资源。要 SSR，先装适配器：

npx astro add cloudflare

装好后，Wrangler 配置文件（wrangler.jsonc）会被自动创建。一个静态托管的典型配置：

{
  "name": "my-astro-app",
  "compatibility_date": "2026-08-07",
  "assets": {
    "directory": "./dist"
  }
}

SSR 形态则要指向 Worker 入口，并通常加 nodejs_compat 等兼容标志：

{
  "main": "dist/_worker.js/index.js",
  "name": "my-astro-app",
  "compatibility_date": "2026-08-07",
  "compatibility_flags": ["nodejs_compat"],
  "assets": {
    "binding": "ASSETS",
    "directory": "./dist"
  }
}

部署命令是：

npx astro build && npx wrangler deploy

本地预览用：

npx astro build && npx wrangler dev

Cloudflare 也支持 CI/CD（比如 Workers Builds）：把仓库导入 Cloudflare 控制台，构建命令设 npx astro build、部署命令设 npx wrangler deploy，之后推代码自动部署。

Cloudflare 上有两个常见坑：一是想用自定义 404 页，要在 wrangler.jsonc 的 assets 里加 "not_found_handling": "404-page"；二是客户端水合可能因 Cloudflare 的 Auto Minify 失败（控制台报 Hydration completed but contains mismatches），关掉 Auto Minify 即可。另外，SSR 时若用到 Node.js 运行时 API，要确保包兼容 Cloudflare 的 Node 兼容层。

三家差异一览

下面这张表把关键差异摆在一起，方便你快速对比：

维度	Vercel	Netlify	Cloudflare
官方适配器	@astrojs/vercel	@astrojs/netlify	@astrojs/cloudflare
安装命令	npx astro add vercel	npx astro add netlify	npx astro add cloudflare
静态部署	零配置，推 Git 即部署	零配置，构建 astro build、发布 dist	用 Wrangler 部署 dist/
SSR 部署	装适配器后零配置	装适配器后零配置	装适配器 + wrangler deploy
部署工具	Git UI 或 vercel CLI	Git UI 或 netlify CLI	wrangler CLI 或 CI/CD
配置文件	可选 vercel.json	可选 netlify.toml	wrangler.jsonc（自动生成）
边缘能力	Edge Functions	Edge Functions	原生边缘（Workers）
个性注意点	几乎零摩擦	旧镜像需设 Node 版本	需处理 404、Auto Minify、Node 兼容

怎么选

• 想要「推上去就跑、几乎不管配置」：Vercel 或 Netlify 都合适，生态成熟、文档友好。
• 看重边缘网络和免费额度：Cloudflare 有优势，但要接受 Wrangler 这套工作流和少数兼容细节。
• 静态站点：三家都能零配置托管，挑你顺手的。
• SSR 站点：三家适配器都完善，差异主要在部署工具链和边缘能力上。

延伸：实验性 CDN 缓存提供商

呼应第 49 章的路由缓存：Astro 7.2 起提供了实验性的 CDN 缓存提供商（如 cacheNetlify、cacheVercel、cacheCloudflare）。它们目前仍是实验特性、需要手动启用，启用后能把缓存指令直接下推到平台边缘网络：

// 以 Netlify 为例（实验性）
import { cacheNetlify } from '@astrojs/netlify/cache';
export default defineConfig({
  cache: { provider: cacheNetlify() },
});

命中时由 CDN 直接返回，不再触发服务器函数，进一步省钱提速。这些是实验特性，正式使用前请以官方文档的当前说明为准，避免踩未稳定的 API。

通用故障排查

部署失败或上线后不对劲，按这个顺序查：

1. 构建在本地能过吗？ 先本地 astro build，不过的话平台也救不了。常见是 site 没填、适配器没装、或某页面代码报错。
2. 适配器装对了吗？ 确认 astro.config.mjs 里 integrations 有对应适配器，且 output 与部署类型匹配。用 npx astro add 一般不会漏。
3. 发布目录对吗？ Vercel/Netlify 默认认 dist，如果你改了 outDir，要在平台设置里同步改。
4. 构建命令对吗？ 应是 astro build（或 npm run build）。别写成 astro dev，那是开发服务器，不能用于生产。
5. 环境变量漏了吗？ SSR 依赖的私密变量要在平台控制台补，本地 .env 不会自动带上云。
6. Cloudflare 特例：404 不显示自定义页就加 not_found_handling；水合报错就关 Auto Minify；Node API 报错就查 nodejs_compat 兼容。

多数部署问题落在这六类里，逐项排除基本都能解决。

小结

三家部署的「主干」高度一致：加适配器 → 定 output → 构建 → 部署。差异集中在 Cloudflare 用 Wrangler、Vercel/Netlify 偏零配置。理解这张对比表，你就能在任意一家把 Astro 站点稳稳送上生产环境。