基于 Cloudflare 的全栈免费技术栈探索：Next.js + Hono + oRPC + Drizzle + D1 + KV 一键部署方案

基于 Cloudflare 的全栈免费技术栈（Next.js + Hono + oRPC + Drizzle + D1 + KV）可通过开源项目 nn-stack 实现一键部署，满足 0 成本、前后端分离、类型安全等核心需求。以下是详细技术解析与部署方案：

1. 前端：Next.js（Pages Worker）

   渲染模式自由切换：支持纯客户端渲染（CSR）或边缘端服务端渲染（Edge SSR），通过 next.config.js 配置。

   类型安全 API 集成：通过 oRPC 自动生成 TypeScript 类型定义，前端直接调用 useQuery/useMutation Hooks（基于 TanStack Query）。

   部署优化：静态资源托管于 Cloudflare Pages，动态请求通过 fetch 指向后端 Worker URL。

2. 后端：Hono（Worker）

   独立部署架构：与前端完全分离，运行在 Cloudflare Workers 环境，支持中间件扩展（如 CORS、日志）。

   oRPC 类型绑定：后端 API 定义通过 @orpc/server 装饰器标记，自动生成前端可用的类型与 Hooks。

   轻量级路由：Hono 的路由语法简洁，例如：

   app.get('/api/data', async (c) => { const data = await D1.query(`SELECT * FROM table`); return c.json(data);});

3. 数据库：D1（SQL） + KV（键值存储）

   Drizzle ORM 集成：通过 drizzle-orm 实现类型安全的 SQL 操作，示例：

   import { sql } from 'drizzle-orm/d1';const users = await db.select().from(usersTable).where(eq(usersTable.id, 1));

   自动初始化：部署时 Alchemy Run 自动执行 Drizzle 的迁移脚本（schema.sql），无需手动创建表。

4. API 层：oRPC（全栈共享）

   单一类型定义：API 接口通过 interface 定义，例如：

   interface API { getUser: { input: { id: number }; output: { name: string; email: string }; };}

   双向类型生成：后端通过 @orpc/server 生成路由处理器，前端通过 @orpc/client 生成 Hooks，确保类型一致。

5. 部署自动化：Alchemy Run

   零配置流程：通过 OAuth 授权 Cloudflare 账号后，自动完成以下操作：

   创建 D1 数据库与 KV 命名空间。

   绑定环境变量（如 D1_DATABASE_ID、KV_NAMESPACE）。

   部署前端（Pages）与后端（Worker）代码。

   命令行操作：

   npx alchemy-run@latest deploy --token YOUR_CLOUDFLARE_TOKEN

1. 环境准备

   注册

   Cloudflare 账号
   并开通 Workers 与 Pages 服务。

   安装 Node.js（建议 LTS 版本）与 wrangler CLI：

   npm install -g @cloudflare/wrangler

2. 克隆开源项目

   git clone
   https://github.com/nshen/nn-stack.gitcd
   nn-stacknpm install

3. 配置 Alchemy Run

   在项目根目录创建 .alchemy 文件，填入 Cloudflare API Token（需包含 Workers 与 D1 权限）。

   修改 wrangler.toml 中的 account_id 与 zone_id。

4. 执行部署

   npm run deploy

   脚本会自动触发 Alchemy Run，完成以下步骤：

   初始化 D1 数据库（执行 drizzle-kit generate:sql）。

   编译前端（Next.js）与后端（Hono）代码。

   创建 Cloudflare Pages 项目并上传前端资源。

   部署 Worker 并绑定数据库变量。

5. 验证部署

   前端访问：

   https://<your-project>.pages.dev

   后端 API 测试：

   curl
   https://<your-worker>.workers.dev/api/data

1. 跨域问题

   Hono 后端默认启用 CORS 中间件，可在 src/server/index.ts 中配置：

   app.use('*', cors({ origin: ['
   https://<your-project>.pages.dev'
   ], allowedMethods: ['GET', 'POST'],}));

2. 类型安全调试

   使用 VS Code 的

   TypeScript 插件
   实时检查 oRPC 生成的类型。

   前端调用 API 时，若类型不匹配会直接报错（如参数缺失或类型错误）。

3. 数据库迁移

   修改 src/db/schema.ts 后，运行以下命令生成迁移脚本：

   npx drizzle-kit generate:sql --schema=./src/db/schema.ts --out=./migrations

   下次部署时 Alchemy Run 会自动执行迁移。

• 适用场景：

  个人博客、小型 SaaS 应用、创业项目 MVP。

  需要快速验证想法且预算有限的团队。

• 当前限制：

  D1 数据库免费层有性能限制（QPS 约 100）。

  Worker 执行时间默认 10ms，复杂计算需优化或升级套餐。

总结：该技术栈通过 Cloudflare 原生服务与自动化工具链，显著降低了全栈开发门槛。独立开发者可借助 nn-stack 快速启动项目，聚焦业务逻辑而非基础设施配置。项目开源地址：