企业官网建设流程全解析

• CLI
• 后端
• 云原生

导读

本文以 vercel 仓库中的 Hono 示例 为主线，完整讲解一个基于 Web 标准的 Hono 应用如何通过 Vercel CLI 完成「本地开发 → 本地构建 → 云端部署」的全流程。读完本文，你将掌握vc dev、vc build、vc deploy三个核心命令的用途与区别，理解示例应用的目录结构与默认导出约定，并了解 Vercel 平台如何自动识别 Hono 框架并为其生成路由与运行时适配。

一、示例项目结构一览

Hono 示例位于仓库的 examples/hono 目录下，是一个极简但完整的可部署项目：

examples/hono/ ├── README.md # 本文档：官方提供的开发/构建/部署三步曲 ├── package.json # 项目清单：声明 hono 依赖与 TypeScript 开发依赖 ├── tsconfig.json # TypeScript 编译配置（NodeNext 模块、strict 模式） └── src/ └── index.ts # 应用入口：导出一个 Hono 实例

其中package.json声明了项目类型为 ESM（"type": "module"），运行时依赖为hono（版本^4.8.9），开发依赖为@types/node与typescript；tsconfig.json采用module: "NodeNext"、strict: true，并启用了hono/jsx作为 JSX 源，说明该示例不仅支持纯路由响应，还具备使用 Hono JSX 渲染视图的能力。

二、应用入口：默认导出 Hono 实例

核心代码位于 src/index.ts，全文如下：

import { Hono } from 'hono' const app = new Hono() const welcomeStrings = [ "Hello Hono!", "To learn more about Hono on Vercel, visit https://vercel.com/docs/frameworks/backend/hono", ] app.get('/', (c) => { return c.text(welcomeStrings.join('\n\n')) }) export default app

这里有三个关键点，决定了它在 Vercel 上的可部署性：

1. 创建实例：new Hono()生成一个 Hono 应用对象，app.get('/', handler)注册根路径的路由；
2. 返回文本响应：处理器通过c.text(...)直接返回纯文本内容，无需额外配置响应头或模板；
3. 默认导出：export default app是 Vercel 识别 Hono 应用的入口约定。从框架检测源码（见下文）可以看出，Vercel 的构建器会按app.*、index.*、server.*、src/index.*等入口文件扫描项目，并配合「默认导出 Hono 实例」的约定完成运行时适配，因此入口文件必须使用默认导出。

三、本地开发：npm install 与 vc dev

原文档给出的本地开发流程如下：

npm install vc dev

open http://localhost:3000

逐步拆解：

• npm install：安装hono运行时依赖以及typescript、@types/node等开发依赖，是后续一切命令的前提；
• vc dev：启动 Vercel CLI 的本地开发服务器。它会在本机模拟 Vercel 的运行时与路由行为，让你在部署前就能验证应用行为。启动成功后访问http://localhost:3000，即可看到根路径返回的Hello Hono!文本。

vc dev的价值在于「本地即生产」：它复用了 Vercel 平台对框架的检测与路由逻辑，因此本地表现与云端表现高度一致，可提前发现路由、环境变量、Serverless 函数边界等问题。

四、本地构建验证：vc build

在部署前，官方文档建议先执行本地构建：

npm install vc build

vc build会在本地执行一次完整的生产构建流程：检测框架类型、解析入口、生成构建产物（Build Output），从而在真实部署前验证项目能否被 Vercel 正确打包。如果项目存在配置错误（如入口缺失、依赖不完整），此步骤会提前暴露问题，避免把错误提交到云端。

从仓库的测试结构可以印证这一点：examples/tests/integration/hono.test.ts 中的集成测试通过deployExample('hono')对示例执行真实的部署验证，说明该示例是被持续测试覆盖的「官方可用模板」；而 packages/hono/test/fixtures 下则准备了从index.js、src/index.ts到server.mts等十余种入口形态的夹具，用于验证构建器在不同入口/模块体系下的适配行为。

五、正式部署：vc deploy

完成本地验证后，即可发布：

npm install vc deploy

vc deploy将项目上传至 Vercel 平台并触发云端构建与发布。对于 Hono 这类「零配置」框架，无需编写vercel.json或自定义构建命令——Vercel 会自动完成框架识别、运行时选择与路由生成。

六、源码佐证：Vercel 如何识别 Hono 应用

Vercel 之所以能对 Hono 项目做到开箱即用，是因为框架清单中内置了 Hono 的完整检测规则。在 packages/frameworks/src/frameworks.ts 中可以看到slug: 'hono'的框架定义，其关键信息包括：

• 检测规则（detectors）：要求项目的package.json中匹配到hono依赖（matchPackage: 'hono'），同时在app.js、index.ts、server.mjs、src/index.ts等常见入口文件中匹配到对hono的 import/require 语句（对应正则(?:from|require|import)\s*...["']hono["']...）；
• 运行时适配（useRuntime）：指定@vercel/hono运行时，将 Hono 应用包装为 Vercel Functions 可执行的形态；
• 默认路由（defaultRoutes）：先处理文件系统资源（handle: 'filesystem'），再将其余请求全部转发给应用入口（src: '/(.*)'、dest: '/'），保证 SPA/动态路由都能正确回落到 Hono 处理器；
• 依赖标识：dependency: 'hono'用于依赖树分析。

这解释了为什么本文示例只需src/index.ts+package.json两个要素即可部署：只要入口文件默认导出了 Hono 实例，构建器就能自动完成其余工作。与之配套的还有 packages/hono 这个独立包，内含 Hono 运行时的构建适配实现（src/index.ts、src/prepare-cache.ts）与大量单元/夹具测试，进一步说明 Hono 是 Vercel 官方维护的一等公民运行时。

七、常见问题与排错思路

• 访问 3000 端口无响应：确认vc dev仍在运行，且入口文件确实位于检测路径内（根目录或src/下的index.*/app.*/server.*）；
• vc build报错找不到入口：检查是否缺少export default app，以及package.json中的依赖是否已安装；
• 部署后路由 404：Hono 默认路由会将所有请求交给应用入口处理，若出现 404，请检查路由注册是否正确，以及是否自定义了会覆盖默认路由的vercel.json；
• TypeScript 编译问题：示例的tsconfig.json启用了strict与verbatimModuleSyntax，若自行扩展代码，需注意类型导入需使用import type等 ESM 规范写法。

结语

通过npm install+vc dev+vc build+vc deploy这一套命令，一个最小的 Hono 应用即可完成从本地到云端的全生命周期管理。示例仓库（examples/hono/README.md、examples/hono/src/index.ts）提供了开箱即用的模板，而 packages/frameworks/src/frameworks.ts 与 packages/hono 则展示了平台层面的自动检测与运行时适配原理。无论你是想快速验证 Hono 的 Vercel 部署体验，还是为现有 Hono 项目接入 Vercel，这套工作流都值得直接复用。

• CLI
• 后端
• 云原生