部署概览：静态 vs SSR 输出模式

写完网站，下一步就是部署——让它真正跑在互联网上。Astro 的部署非常灵活，但前提是你得先理解「输出模式」这个开关。这一章先把全局概念讲透，第 51 章再具体到平台。

一个关键配置：output

Astro 怎么构建、构建出什么，由一个配置项决定：output。它有三个取值。注意：旧的 ssr: true 写法在 v4 就被废弃了，现在一律用 output，别再写 ssr。

• static（默认）：构建出纯静态文件（HTML/CSS/JS/图片），不依赖服务器运行时。
• server：按需渲染（on-demand rendering，也就是常说的 SSR），每个请求由服务器现渲染。
• hybrid：混合模式。默认当静态处理，但你可以用 export const prerender = false 把个别页面/端点标成按需渲染。

// astro.config.mjs
import { defineConfig } from 'astro/config';

export default defineConfig({
  output: 'static', // 也可填 'server' 或 'hybrid'
});

如果你不写 output，Astro 默认就是 static。这也是 Astro 最常见、最省心的用法。

静态部署：零运行时的省心方案

output: 'static'（或不写）时，Astro 在构建期就把所有页面渲染成 HTML 文件。部署时你只要把这些文件丢到任意能托管静态文件的地方——对象存储、静态主机、CDN、甚至 GitHub Pages 都行。

静态部署的好处：

• 不需要服务器、不需要运行时，成本极低甚至免费。
• 页面是现成的文件，CDN 直接分发，速度极快、抗压能力强。
• 维护简单，没有「服务器挂了」这种烦恼。

代价是：页面内容在构建时就固定了。需要实时数据的部分（比如登录用户态、实时库存、表单后端），要靠岛屿、server:defer 的服务端岛屿，或单独的 API 来补。但主体内容依旧是静态的，这正是 Astro 的强项。

SSR 部署：需要适配器加运行环境

当你设 output: 'server'（或 hybrid 里把某些页标成 prerender = false），页面改成「每次请求现渲染」。这时光有静态文件不够了，你需要两样东西：

1. 一个适配器（adapter）。适配器负责把 Astro 的渲染逻辑翻译成目标运行环境能跑的形式。比如 @astrojs/node、@astrojs/vercel、@astrojs/netlify、@astrojs/cloudflare 等。
2. 一个运行环境。也就是真正能执行这段服务器代码的地方：Node 服务器、各平台的 Serverless/边缘函数等。

装适配器通常用官方命令，比如：

npx astro add vercel

这条命令会装包并自动改好 astro.config.mjs。第 51 章会细讲三个主流平台的适配器。

什么时候该用 SSR

不是所有站点都需要 SSR。下面这些情况，考虑用 server 或 hybrid：

• 页面内容高度依赖请求（用户身份、地理位置、A/B 实验）。
• 数据频繁变化，你又不想每次都整站重新构建。
• 需要服务端处理表单、会话（sessions，第 54 章）、Actions（第 45 章）。
• 用到了按需渲染才有的能力（Server Islands、astro:server 等）。

如果只是博客、文档、营销页这类「内容为主、更新不频繁」的站点，static 几乎总是最优选。Astro 的群岛架构让静态页也能有交互，所以「想要交互」并不等于「必须 SSR」。

一句话判断：默认静态，只有「不现渲染就做不了」时才上 SSR。

构建命令与产物

无论哪种模式，构建都靠一条命令：

npm run build

它等价于 astro build。构建完成后，产物默认放在项目根目录的 dist/ 文件夹下。这个位置可以用配置项的 outDir 改。

• 静态模式：dist/ 里是一堆 .html、CSS、JS、图片，直接可托管。
• SSR 模式：dist/ 里除了静态资源，还有服务器入口和函数代码，需要配好适配器对应的运行环境才能跑。

如果你用 pnpm 或 yarn，把 npm run build 换成 pnpm run build / yarn run build 即可。

本地预览：astro preview

构建完想先在本地看看效果，用预览命令：

npm run preview

它启动一个本地服务器，按生产构建的方式提供 dist/ 里的内容。对静态站点，预览就是直接托管文件；对 SSR 站点，预览需要适配器支持（Node 适配器一般开箱即用）。

提醒：开发模式 astro dev 和预览 astro preview 行为可能不同（比如缓存、按需渲染的表现），上线前用 preview 验证一遍更稳妥。

部署的共性步骤

不管是哪个平台，部署流程大体是这几步：

1. 本地 npm run build 构建（很多平台也会在云端自动构建）。
2. 确认 output 模式与你要的部署类型匹配。
3. SSR 的话，先装好对应适配器并配进 astro.config.mjs。
4. 把 dist/ 产物交给平台（平台自动构建的，就推送代码让它构建）。
5. 配置域名、环境变量等。
6. 访问上线地址，验证页面、交互、缓存是否正常。

第 51 章就按「Vercel / Netlify / Cloudflare」三家的差异，把第 3 步及之后的平台特定操作讲清楚。

server 模式要注意的几件事

选了 output: 'server' 或 hybrid 后，有几处和静态部署不同，提前心里有数：

• 不能只靠静态托管。你必须提供运行环境（Node 服务、Serverless、边缘函数），光传 dist/ 文件到静态主机是跑不起来的。
• 冷启动与成本。SSR 每次请求都可能触发一次函数或进程，函数平台常按调用次数/时长计费，流量大时成本会出现，要关注。路由缓存（第 49 章）正是用来缓解这个的。
• 环境变量要配在平台侧。服务端代码读取的私密变量（如 API key）得在平台控制台设置，不能只放本地 .env。
• astro preview 依赖适配器。不是所有适配器都支持本地预览，Node 适配器一般可以，部署前确认一下。

换句话说，SSR 给你灵活性，也带来运维负担。能用静态解决的，尽量静态。

部署清单小抄

• site 配置填了正式域名（sitemap、RSS、canonical 都依赖它）。
• output 选对（static / server / hybrid）。
• SSR 场景已 npx astro add <适配器>。
• 静态资源（图片、字体）走 public/ 或 astro:assets。
• 本地 astro build 无报错，astro preview 验证通过。
• 平台侧构建命令 astro build、发布目录 dist 已确认。

把这几点过一遍，部署基本不会踩大坑。

构建失败先查这几处

部署前本地 astro build 偶尔会报错，多数集中在几类，按顺序排查能省不少时间：

• 内存不足：大站整站构建吃内存，CI 默认配额偏小会崩。优先开 Astro 7.2 的实验性增量静态构建（只重建变化的页），或给构建进程加内存。
• 适配器没装 / 装错：SSR 模式忘了 astro add 适配器，或 output 与适配器不匹配，构建会直接报缺运行时。
• 内容层 loader 配置错：集合的 loader 路径或参数写错，构建期取数失败，报错通常指向 src/content.config.ts。
• 版本不兼容：本地 Astro 和适配器大版本差太多会踩 breaking change，升级后先看官方升级指南再部署。

这类问题在构建期就暴露，比上线后再发现要好处理得多。