Vercel 零配置部署 Fastify：@vercel/fastify 适配器源码级解析与实战指南

• CLI
• 后端
• 云原生

导读

本篇文章围绕 packages/fastify/CHANGELOG.md 展开，深入解读@vercel/fastify这个 Vercel 官方适配器包的核心演进：从 0.1.0 引入 Fastify 零配置支持，到 0.1.17 导出prepareCache构建缓存函数，再到后续随@vercel/node、@vercel/static-config的持续同步更新。读完本文，你将掌握 Fastify 应用如何在 Vercel 上实现免配置部署、构建器如何自动识别入口文件与检测框架、prepareCache如何加速增量构建，以及本地开发与部署的完整命令流程。

一、什么是 @vercel/fastify：CHANGELOG 背后的适配器包

@vercel/fastify是 Vercel 仓库中面向 Fastify 框架的官方构建适配器，位于 packages/fastify，核心源码仅两个文件：

• src/index.ts：包的主入口，导出version、build、shouldServe、startDevServer、prepareCache与diagnostics；
• src/prepare-cache.ts：构建缓存函数实现。

包配置见 packages/fastify/package.json，其依赖@vercel/static-config与@vercel/node均以workspace:*形式引用，这正是 CHANGELOG 中大量 "Updated dependencies" 条目的来源。

从 CHANGELOG 中提炼关键信息

通读整个 CHANGELOG，可以归纳出三类信息：

1. 功能里程碑：0.1.0 新增 Fastify 零配置支持（PR #14120）；0.1.17 为后端构建器导出prepareCache函数（PR #14454）。
2. 依赖同步：绝大多数 Patch Changes 仅是@vercel/node（自 5.5.0 至 5.9.3）或@vercel/static-config（3.2.0 / 3.3.0 / 3.4.0）版本升级的跟随记录，说明该包没有独立逻辑变更，而是随底层运行时迭代。
3. 工程维护：0.1.16 改为使用workspace:*声明工作区依赖（PR #14396），使 monorepo 内依赖引用更稳健。

本文重点围绕 0.1.0 与 0.1.17 两个功能性变更展开。

二、零配置支持（0.1.0）：构建器如何自动工作

0.1.0 的 "Add zero-config support for Fastify" 意味着：开发者无需编写任何 Vercel 配置（如vercel.json的 build 命令或路由），仅凭项目结构即可部署。

2.1 构建器定义：generateNodeBuilderFunctions

src/build.ts 通过@vercel/build-utils的generateNodeBuilderFunctions工厂函数生成build、entrypointCallback、findEntrypoint等函数，关键参数：

export const { build, entrypointCallback, findEntrypoint, require_ } = generateNodeBuilderFunctions( 'fastify', // 框架名 /(?:from|require|import)\s*(?:\(\s*)?["']fastify["']\s*(?:\))?/g, // 导入检测正则 ['app', 'index', 'server', 'src/app', 'src/index', 'src/server'], // 候选入口名 ['js', 'cjs', 'mjs', 'ts', 'cts', 'mts'], // 支持的文件扩展名 nodeBuild // 底层 Node 构建器 );

这一机制的实现在 packages/build-utils/src/generate-node-builder-functions.ts：

• 入口检测顺序：先看projectSettings.outputDirectory指定的输出目录，再看项目根目录。入口文件名按{app,index,server,src/app,src/index,src/server}.{js,cjs,mjs,ts,cts,mts}的 glob 模式扫描；
• 内容匹配：对候选文件读取内容，用导入检测正则判断是否真的import/require了fastify，只有匹配的文件才被认定为入口。若存在同名但未导入 fastify 的文件，会抛出明确错误，提示找到的可能入口列表；
• package.json main 回退：若常规入口均不匹配，会回退到package.json的main字段指定的文件，且同样要求其内容匹配导入正则；
• 多入口警告：若匹配到多个入口，仅取第一个并打印警告；
• 版本回填：构建完成后尝试解析fastify/package.json，将框架 slug 与版本写入output.framework。

2.2 框架检测与路由：frameworks 注册表

零配置的起点是框架检测。Vercel 的框架注册表 packages/frameworks/src/frameworks.ts 中注册了 Fastify 条目：

{ name: 'Fastify', slug: 'fastify', supersedes: ['node'], // 优先级高于通用 Node 检测 useRuntime: { src: 'index.js', use: '@vercel/fastify' }, // 指向本适配器 defaultRoutes: [ { handle: 'filesystem' }, { src: '/(.*)', dest: '/' }, // 兜底路由到入口 ], detectors: { every: [{ matchPackage: 'fastify' }], // 项目必须依赖 fastify some: [ /* 一系列候选入口文件 + 导入检测正则 */ ], }, settings: { installCommand: { placeholder: '`yarn install`, `pnpm install`, `npm install`, or `bun install`' }, buildCommand: { value: null }, // 无需构建命令 devCommand: { value: null }, outputDirectory: { value: 'N/A' }, }, }

检测规则：项目必须满足every（依赖中声明了fastify包），并且至少一个some条件命中——即某个候选入口文件（如app.js、server.mjs、src/index.ts等）内容中出现了对fastify的导入。检测通过后，useRuntime指向@vercel/fastify运行时，实现零配置接管。默认路由先服务静态文件系统，其余路径兜底到入口。

2.3 路由与 API 路由的协作：shouldServe

src/index.ts 中定义了shouldServe，决定本地开发服务器（vercel dev）对某请求是否自行处理：

export const shouldServe: ShouldServe = async opts => { const requestPath = opts.requestPath.replace(/\/$/, ''); // 去掉尾部 '/' if (requestPath.startsWith('api') && opts.hasMatched) { return false; // 不覆盖 API 路由，交给 API 处理器 } return true; // public 静态资源由默认处理器兜底 };

可见 Fastify 适配器刻意不与项目中的api/*目录路由冲突：匹配到的 API 路由优先，其余请求（包括 Fastify 自身路由）交由适配器服务。

三、构建缓存：prepareCache（0.1.17）

0.1.17 的变更 "Export prepareCache function for backend builders" 为包新增了缓存导出。实现位于 src/prepare-cache.ts：

import type { PrepareCache } from '@vercel/build-utils'; import { glob, defaultCachePathGlob } from '@vercel/build-utils'; export const prepareCache: PrepareCache = ({ repoRootPath, workPath }) => { return glob(defaultCachePathGlob, repoRootPath || workPath); };

其缓存范围由 packages/build-utils/src/default-cache-path-glob.ts 定义：

export const defaultCachePathGlob = '**/{node_modules,.yarn/cache}/**';

作用机制：prepareCache在构建前将项目中的node_modules（以及 Yarn 的.yarn/cache离线缓存）打捞为缓存文件，下次部署时直接复用，跳过重新npm install的下载与解析开销。这是 Fastify 项目在 Vercel 上实现增量构建加速的关键一环。该函数由 packages/backends/src/index.ts 中对应的 Node 后端实现所承接，构成从适配器到后端构建器的完整调用链。

四、本地开发与部署实战

4.1 官方示例项目

仓库提供了可直接运行的 Fastify 示例，位于 examples/fastify：

• 入口文件 server.ts：使用 ESM + TypeScript，fastify.get('/')返回带样式的 HTML 页面；
• package.json：声明"type": "module"，依赖fastify@5.6.1，devDependencies 含typescript@5.8.3；
• tsconfig.json：module: NodeNext，适配 ESM 模块解析。

4.2 标准命令流程

依据 examples/fastify/README.md：

本地开发：

npm install vc dev

启动后访问http://localhost:3000。vc dev会调用上文所述的startDevServer——src/index.ts 中它会先通过entrypointCallback定位 Fastify 入口并生成 shim 文件，随后设置EXPERIMENTAL_NODE_TYPESCRIPT_ERRORS=1并转交@vercel/node的开发服务器。shim 放置在 gitignore 位置，不污染用户仓库。

本地构建：

npm install vc build

部署上线：

npm install vc deploy

三者都无需任何框架专属配置，正是 0.1.0 "zero-config" 的直接体现。

4.3 典型项目结构

从构建器的入口扫描逻辑（见 2.1 节）与框架检测规则（见 2.2 节）可以推断，一个可被零配置识别的 Fastify 项目至少需要：

project/ ├── package.json # 必须声明 fastify 依赖 ├── server.mjs # 或 app.js / index.ts / src/server.ts 等候选入口 └── public/ # 可选：静态资源目录，由默认 filesystem 处理器服务

入口文件内必须包含类似import Fastify from 'fastify'的导入语句，检测正则才会命中。

五、测试验证与工程质量

包内附带单元测试 packages/fastify/test/unit/build.test.ts，使用 Vitest 驱动：

• 测试夹具为 packages/fastify/test/fixtures/01-basic，其 server.mjs 是 Fastify 官方的极简示例：Fastify({ logger: true })、fastify.get('/')返回{ hello: 'world' }、listen({ port: 3000 })；
• 测试以zeroConfig: true、framework: 'fastify'、Node22.x的配置调用build，断言构建产物output.handler为server.mjs，并校验生成的 shim 文件为 ESM 模块类型；
• 这印证了 0.1.0 零配置构建的实际行为：输入一个仅含package.json+server.mjs的最小项目，构建器即可正确定位入口并产出可部署产物。

六、版本演进脉络总结

将 CHANGELOG 中的关键节点整理如下：

规律解读：@vercel/fastify的适配器逻辑自 0.1.17 后保持稳定，后续版本主要是随底层@vercel/node运行时与@vercel/static-config配置解析库的迭代而同步发布，保证 Fastify 部署始终跟随最新的 Node 构建与配置解析能力。当前包版本为 0.1.110（见 packages/fastify/package.json）。

七、总结

@vercel/fastify通过generateNodeBuilderFunctions工厂与框架注册表的组合，实现了 Fastify 项目的零配置识别、入口自动定位与部署；prepareCache利用node_modules/.yarn/cache缓存加速增量构建；shouldServe与startDevServer则保证了本地开发体验与 API 路由的和谐共存。对于想要在 Vercel 上快速托管 Fastify 应用的开发者，只需保持package.json声明 fastify 依赖、入口文件导入 fastify，即可按vc dev/vc build/vc deploy三步完成从本地到线上的全部流程。

• CLI
• 后端
• 云原生