适配器（Adapters）与部署目标

上一章提到”适配器也是一种集成”。它确实特殊——适配器决定你的 Astro 项目最终跑在哪个服务器环境上。本章把它单拎出来，讲清它和”部署目标”的关系。已经学过第 36 章（按需渲染）的同学会有代入感，但即便没细看，本章也能独立读懂。

为什么需要适配器

默认情况下，Astro 在构建时把所有页面生成静态 HTML。但一旦你想让某些页面按需渲染（第 36 章：访客请求时才生成），就需要有一台服务器在访客到来时现跑代码、现出页面。这块”让服务器能跑你的项目”的活儿，就由**适配器（adapter）**干。

适配器的作用，是让 Astro 输出一段能在特定**运行环境（runtime）**上执行的脚本。运行环境就是”在服务器上真正生成页面的地方”，比如 Netlify、Cloudflare、Vercel，或者一台普通的 Node 服务器。换句话说：不同的部署平台，要用对应的适配器。

官方适配器清单

Astro 官方维护四类主流适配器，对应四大部署生态：

• @astrojs/node：跑在 Node.js 服务器上。适合自托管、Docker、传统服务器。
• @astrojs/vercel：部署到 Vercel。
• @astrojs/netlify：部署到 Netlify。
• @astrojs/cloudflare：部署到 Cloudflare（Pages / Workers）。

社区还有更多适配器（比如 @deno/astro-adapter 跑在 Deno 上等），都在 Astro 集成市场按 “adapters” 分类可查。选哪个，看你的部署环境。

怎么装适配器

和别的集成一样，最省事的是 astro add：

npx astro add netlify
pnpm astro add netlify
yarn astro add netlify

它一步装好包并改好 astro.config.mjs。也能手动 npm install @astrojs/netlify 再自己写配置。不同适配器配置项不同，读各自文档。

适配器在配置里长什么样

装好后，配置里会同时出现 output（输出模式）和 adapter（适配器）两项，二者配套：

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

export default defineConfig({
  output: 'hybrid',      // 或 'server'
  adapter: netlify(),    // 装好的适配器
});

只要存在按需路由，output 就不能是默认的 static，且必须配 adapter。纯静态站点可以没有适配器。

适配器与部署平台的对应

适配器是”部署”的技术前提。每个平台的具体部署流程（连账号、设环境变量、绑定域名）是另一个话题，本教程部署模块（第 50、51 章）会讲共通步骤与代表平台差异。这里只建立一张映射表：

• 想部署到 Vercel → 装 @astrojs/vercel。
• 想部署到 Netlify → 装 @astrojs/netlify。
• 想部署到 Cloudflare → 装 @astrojs/cloudflare。
• 想跑在自己的 Node 服务器 / Docker → 装 @astrojs/node。

静态适配器与 SSR 适配器

从能力上看，适配器可分两类思路：

• 静态优先平台：很多平台（如 Netlify、Vercel、Cloudflare）既能托管纯静态产物，也能在装了适配器后跑按需渲染。装适配器是”解锁动态能力”的开关。
• 纯 Node 运行时：@astrojs/node 把项目输出成 Node 可执行的服务器程序，适合你完全掌控的机器或容器。

无论哪类，逻辑一致：适配器把”Astro 的项目”翻译成”目标环境认得的运行形式”。

运行环境（runtime）到底是什么

“运行环境”这个词听着抽象，其实就一句话：你的代码最终在哪台机器、哪种引擎上跑。Node 运行环境跑在 Node.js 上；Vercel / Netlify / Cloudflare 各有自己的函数运行时。适配器的工作，就是把 Astro 的项目”翻译”成目标运行环境认得的产物。所以选适配器，本质是选”我的代码将来在哪跑”。

各平台适配器的最小配置示例

虽然具体部署流程留到部署章节，但看看配置长相有帮助。

Vercel：

import vercel from '@astrojs/vercel';
export default defineConfig({ output: 'hybrid', adapter: vercel() });

Cloudflare：

import cloudflare from '@astrojs/cloudflare';
export default defineConfig({ output: 'hybrid', adapter: cloudflare() });

Node（输出成可用 node 跑的服务器）：

import node from '@astrojs/node';
export default defineConfig({ output: 'server', adapter: node({ mode: 'standalone' }) });

注意 @astrojs/node 常用 mode: 'standalone'（独立可跑）或 'middleware'（作为中间件嵌入已有 Node 服务），具体看文档。

选平台的简易判断

• 想要最省心、推上去就部署 → Vercel / Netlify。
• 想要边缘网络、全球低延迟 → Cloudflare。
• 想要完全自己掌控、跑容器 → Node 适配器 + 你自己的服务器。

无论选谁，“按需渲染就必须有对应适配器”这条不变。

不装适配器会怎样

如果你在配置里设了 output: 'server' 或 'hybrid'，却没装适配器，构建时会直接报错——Astro 不知道该把项目输出成哪种运行形式。所以”按需渲染”和”适配器”是绑定的：要么全静态（不需要适配器），要么按需（必须装）。这也解释了为什么纯静态站点部署最简单：没有适配器、没有运行时依赖，丢到任何静态托管都行。

环境变量与密钥

适配器把项目部署到平台后，平台侧的环境变量（如数据库密码、API Key）要在该平台后台设置，Astro 端用 import.meta.env（第 35 章）读取。不同平台设环境变量的入口不同，但”代码里读 import.meta.env.XXX”这行是统一的。这也是适配器只管”运行形式”、不管”密钥从哪来”的体现。

不同运行时的一个小提醒

适配器背后是「运行时」。不同运行时的脾气不太一样，先有个心理准备：

• Node 运行时最「像本地开发」，你熟悉的 Node API 基本都能用，调试也直观。
• 各平台的「函数运行时」（Vercel / Netlify / Cloudflare）通常是按需启动的，冷启动、执行时长、能用的 API 都有限制。写代码时别假定「服务器一直开着」。
• Cloudflare 跑在边缘，全球低延迟，但它不是标准 Node 环境，某些 Node 专属 API 用不了，挑依赖时要留意。

这些不是适配器本身的配置项，而是「你选了哪个平台」带来的约束。适配器只负责把项目翻译成那个环境认得的样子；至于那个环境能跑什么、不能跑什么，得看平台自己的规则。把这一层想清楚，部署时才不会踩到运行时差异的坑。

小结

适配器决定 Astro 项目跑在哪个服务器环境，是按需渲染的硬性前提。官方四大适配器对应 Node、Vercel、Netlify、Cloudflare；社区还有 Deno 等。用 astro add 安装，并在 astro.config.mjs 里和 output 配套出现。具体怎么部署到各平台，看后续部署章节。

下一章我们回过头，把 astro.config.mjs 整体再梳理一遍，建立一张配置地图。