14 - 技术栈选型指南
本篇面向个人开发者，基于 AI 友好度优先原则给出可落地的技术栈决策框架。 原始素材：AI-First-Tech-Stack-Guide（2025），结合 2025-2026 最新实践增补。
1. 定位
为什么需要专门的技术栈选型指南？
AI 辅助编程改变了技术栈决策的权重：
- 文档质量 > 社区规模 — AI 训练数据中文档丰富的框架被生成得更准确
- 类型信息 > 运行时灵活性 — TypeScript 类型为 AI 提供上下文，Python 动态类型则依赖 docstring
- 约定 > 配置 — 遵循约定的框架（Next.js、FastAPI）比高度自定义框架生成错误更少
- 可读性 > 性能微优化 — AI 理解清晰代码比理解"聪明代码"准确得多
错误的技术栈选型会让 AI 产生大量幻觉，正确的选型让 AI 成为 10 倍效率工具。
2. 核心选型原则（5 大 AI 友好因素）
F1：文档密度（Documentation Density）
AI 的代码质量与框架文档在训练集中的覆盖度正相关。优先选择：有官方文档站、有大量高质量教程、GitHub Stars > 10k 且持续更新。
F2：类型安全（Type Safety）
强类型语言给 AI 提供自动补全所需的上下文。TypeScript 在 2025 年 GitHub 活跃仓库数超越 Python，成为全栈类型安全的首选。
F3：约定优先（Convention over Configuration）
Next.js App Router、FastAPI、Rails 等"约定重于配置"的框架让 AI 能预测文件位置、函数签名和模块关系，减少幻觉。
F4：生态稳定性（Ecosystem Stability）
API 频繁变动的框架会让 AI 生成过时代码。评估维度：版本发布频率、breaking change 策略、LTS 支持情况。
F5：可观测性支持（Observability）
AI 生成代码的 bug 比手写代码更隐蔽，框架对结构化日志、tracing、健康检查的内置支持至关重要。
3. AI 友好度分级（S/A/B/C）
分级标准：AI 代码生成准确率 + 幻觉频率 + 文档密度综合评估。
S 级 — 首选（AI 生成准确率 > 90%）
| 技术 | 类型 | AI 友好理由 |
|---|---|---|
| TypeScript | 语言 | 类型系统为 AI 提供完整上下文；2025 年 GitHub 活跃仓库数超越 Python |
| Next.js 14+ | 全栈框架 | App Router 约定清晰，AI 精准预测文件结构 |
| React 18+ | UI | 训练数据最丰富，Hooks 模式一致性高 |
| FastAPI | Python API | 自动 OpenAPI 文档 + 类型注解，AI 生成准确率极高 |
| Prisma | ORM | 声明式 Schema + 类型安全客户端，AI 可精准推断 |
A 级 — 推荐（AI 生成准确率 80-90%）
| 技术 | 类型 | 说明 |
|---|---|---|
| Tailwind CSS | 样式 | 类名语义化，AI 可预测组合 |
| Hono | 轻量 API | 类型优先设计，Cloudflare Workers 首选 |
| Drizzle ORM | ORM | TypeScript 原生，轻量可预测 |
| LangChain | AI 框架 | 文档丰富，但版本迭代快需注意 |
| LangGraph | Agent 编排 | 结构化工作流；⚠️ API 变动频繁，锁定版本后再用 |
| Vercel AI SDK | AI SDK | TS 原生，统一多模型接口 + Streaming UI |
| Supabase | BaaS | 文档完善，约定强，AI 生成迁移代码准确 |
B 级 — 可用（AI 生成准确率 60-80%）
| 技术 | 类型 | 注意事项 |
|---|---|---|
| Express.js | API | 配置自由度高导致 AI 不确定约定 |
| Vue 3 | UI | 文档好但训练数据量少于 React |
| SQLAlchemy | ORM | 多种写法导致 AI 风格不一致 |
| Nuxt 3 | 全栈 | 生态较小，AI 时有幻觉 |
C 级 — 谨慎（AI 生成准确率 < 60%）
| 技术 | 问题 |
|---|---|
| GraphQL（复杂 Schema） | N+1 问题难以被 AI 自动规避 |
| Webpack 自定义配置 | 配置项组合爆炸，AI 经常产生过时写法 |
| 微服务（早期项目） | AI 无法理解跨服务边界的隐式契约 |
4. 推荐技术栈组合
组合 A：TypeScript 全栈（主力推荐）
适合：SaaS、内容平台、API + 前端一体化项目
前端：Next.js 14+ (App Router) + Tailwind CSS + shadcn/ui
后端：Next.js API Routes 或 Hono (Cloudflare Workers)
数据库：Supabase (PostgreSQL) + Prisma ORM
AI 层：Vercel AI SDK + OpenAI / Anthropic
部署：Vercel (前端) + Supabase Cloud (DB)AI 协作优势：单一语言消除上下文切换，Next.js 约定让 AI 精准定位文件位置。
组合 B：Python 全栈（数据/AI 密集型）
适合：AI Agent、数据处理 pipeline、ML 模型服务
API：FastAPI + Pydantic v2
数据层：SQLAlchemy 2.0 + Alembic (迁移)
AI 层：LangChain / LangGraph + LiteLLM (多模型代理)
任务队列：Celery + Redis
部署：Railway / Render + DockerAI 协作优势：FastAPI 的类型注解和自动文档让 AI 理解 API 契约。
组合 C：轻量 MVP（快速验证）
适合：个人工具、周末项目、概念验证
框架：Hono (TypeScript) 或 FastAPI (Python)
数据：SQLite + Drizzle / Prisma
AI：OpenAI SDK 直调
部署：Cloudflare Workers (零运维) 或 Railway原则：MVP 阶段不引入消息队列、微服务、复杂缓存层。
5. AI / Agent 应用栈
5.1 模型接入层
| 工具 | 场景 | 推荐度 |
|---|---|---|
| Vercel AI SDK | TS 项目首选，统一接口 + Streaming UI | ★★★★★ |
| LiteLLM | Python 多模型代理，统一 OpenAI 格式 | ★★★★☆ |
| OpenAI SDK | 直接调用，最低抽象 | ★★★★☆ |
| Anthropic SDK | Claude 专用，最新特性优先支持 | ★★★★☆ |
5.2 Agent 编排层
Claude Tool Use / MCP（零额外依赖，首选）
- 大多数 Agent 场景不需要额外编排框架
- Claude Code 本身就是高度成熟的 Agent 编排器（工具调用、子代理、Agent Teams）
- 适合：单代理工具链、CLI 自动化、大多数个人项目
LangGraph（复杂状态机工作流）
- 适合：需要可视化状态图、持久化中间状态、人工审批节点的生产级 Agent
- ⚠️ API 变动频繁，务必锁定版本（
langgraph==x.y.z） - 建议：先用 Claude Tool Use，遇到需要状态持久化或条件分支时再引入
CrewAI（角色分工多 Agent）
- 适合：多角色 Agent 协作（研究员 + 撰稿 + 审核）
- ⚠️ 生产部署前锁定版本，框架迁移成本较高
OpenAI Agents SDK
- 特点：内置 handoff 机制，多 Agent 传递简洁
- ⚠️ 锁定在 OpenAI 生态，跨模型迁移困难；仅在已深度使用 GPT 模型时考虑
5.3 工具层
- RAG：Chroma（本地）/ Pinecone（云端）/ pgvector（Supabase 内置）
- 函数调用：OpenAI Function Calling / Anthropic Tool Use
- 浏览器操作：Playwright（AI 生成准确率高）
6. LLMOps 与可观测性
AI 应用的 bug 往往不是代码错误，而是 prompt 漂移、token 超限、模型幻觉。必须从第一天就接入可观测性。
6.1 可观测性 5 大支柱
| 支柱 | 内容 | 工具 |
|---|---|---|
| Tracing | 完整调用链追踪（prompt → 工具调用 → 响应） | Langfuse, LangSmith |
| 评估（Eval） | 输出质量自动化测评 | Langfuse, PromptFoo |
| 成本监控 | Token 用量 + API 费用追踪 | Langfuse, AgentOps |
| 延迟分析 | P95/P99 响应时间，识别瓶颈 | 同上 |
| 错误率 | LLM 调用失败、JSON 解析失败 | 同上 + Sentry |
6.2 工具选型
Langfuse（开源自托管首选）
- 自托管：需 PostgreSQL + docker compose，参考官方文档 self-host 指南
- 云端：
cloud.langfuse.com免费额度详见 cloud.langfuse.com 最新定价 - 集成：
langfusePython SDK，Vercel AI SDK 内置 hook - 适合：注重数据主权的个人/小团队
LangSmith（LangGraph 生态配套）
- LangGraph 用户首选，与 LangChain 生态无缝集成
- 提供 prompt 版本管理和 A/B 测试
AgentOps（Agent 专用）
- 专为多 Agent 系统设计，自动追踪 Agent 间消息传递
- 适合 CrewAI 和 OpenAI Agents SDK 用户
OpenTelemetry（统一可观测性标准）
- 趋势：越来越多项目用 OTEL 做统一 tracing，而非各 LLMOps 平台私有 SDK
- Langfuse、LangSmith 均支持 OTEL 导出
- 适合：已有 OTEL 基础设施的团队，一套 tracing 覆盖 LLM + 传统服务
6.3 最低可行接入（MVP 级别）
python
# FastAPI + LangChain + Langfuse，3 行接入
from langfuse.callback import CallbackHandler
handler = CallbackHandler()
chain.invoke(input, config={"callbacks": [handler]})7. 部署层选型
决策矩阵
| 维度 | Vercel | Cloudflare Workers | Railway |
|---|---|---|---|
| 冷启动 | ~100ms | 零冷启动 | ~500ms |
| 边缘推理 | 否 | ✅ Workers AI | 否 |
| 数据库支持 | Postgres（插件） | D1 (SQLite) / KV | ✅ 原生 |
| 长时运行任务 | ❌（60s 限制） | ❌（CPU 限制） | ✅ |
| 国内访问 | 较慢 | 需评估 | 中等 |
| 月费（个人） | 免费层够用 | 免费层够用 | $5/月起 |
推荐策略
- 纯前端 + API：Vercel（Next.js 原生部署体验最佳）
- 边缘 AI 推理：Cloudflare Workers AI（零冷启动 + 边缘节点，适合全球用户）
- 长时任务 / 数据库密集：Railway（Docker 原生，无 serverless 限制）
- 混合方案：Vercel（前端） + Cloudflare Workers（边缘 API） + Railway（后台任务）
国内用户注意：Cloudflare Workers 在中国大陆未备案域名访问不稳定。 面向国内用户的项目，前端推荐 Vercel + 自定义域名备案，或使用国内云服务（阿里云 FC / 腾讯云 SCF）。 Cloudflare Workers 更适合面向海外用户的场景。
Cloudflare Workers AI 快速入门
typescript
// Hono + Workers AI，边缘推理示例
import { Hono } from 'hono'
const app = new Hono<{ Bindings: { AI: Ai } }>()
app.post('/generate', async (c) => {
const { prompt } = await c.req.json()
const result = await c.env.AI.run('@cf/meta/llama-3.1-8b-instruct', {
messages: [{ role: 'user', content: prompt }]
})
return c.json(result)
})8. 跨端开发
方案对比
| 方案 | 目标平台 | AI 友好度 | 适用场景 |
|---|---|---|---|
| Taro 4 | 小程序 + H5 + RN | ★★★★☆ | 国内多端，微信生态 |
| UniApp | 小程序 + H5 + App | ★★★☆☆ | 国内多端，Vue 语法 |
| React Native + Expo | iOS + Android | ★★★★★ | 海外原生移动端 |
| Tauri 2 | 桌面（Win/Mac/Linux） | ★★★★☆ | 桌面工具，Rust 后端 |
| Electron | 桌面 | ★★★★☆ | 桌面工具，Node 后端 |
选型建议
- 国内 C 端：Taro 4 + React（支持 TS，组件库生态健全）
- 国内 B 端 + 企业微信：Taro 4 或 UniApp（看团队前端栈）
- 海外移动：Expo（托管工作流，零原生配置）
- 桌面工具：Tauri 2（包体积 < 5MB，优于 Electron）
AI 生成跨端代码注意事项
- 明确告知 AI 目标平台（"for Taro 4 mini-program"），否则生成 DOM API 代码无法运行
- 跨端样式规则不同，在 CLAUDE.md 中列出禁用的 CSS 属性
- 平台特定 API（微信支付、相机权限）需提供文档链接给 AI
9. AI 友好的项目实践
9.1 模块结构约定
src/
├── app/ # Next.js App Router（路由即文件）
├── components/ # UI 组件（纯展示）
├── lib/ # 工具函数（纯函数优先）
├── services/ # 业务逻辑（单一职责）
├── types/ # 全局类型定义
└── hooks/ # React Hooks原则：每个文件职责单一，文件名即功能说明。AI 通过路径即可推断文件内容。
9.2 类型定义优先
typescript
// 先定义类型，再写实现 — AI 可基于类型签名精准推断实现
interface UserService {
findById(id: string): Promise<User>
updateProfile(id: string, data: Partial<UserProfile>): Promise<void>
}在 CLAUDE.md 中声明：Always define interfaces before implementation。
9.3 CLAUDE.md AI 友好配置片段
markdown
## Tech Stack
- Framework: Next.js 14 App Router
- Language: TypeScript (strict mode)
- Database: PostgreSQL via Prisma
- AI SDK: Vercel AI SDK
## Code Conventions
- Use server components by default; add 'use client' only when needed
- All async functions must handle errors with try/catch
- Prisma queries in lib/db/ only, never in components
- No `any` type — use `unknown` with type guards
## Forbidden Patterns
- No raw SQL (use Prisma)
- No `console.log` in production code (use structured logger)
- No direct fetch in components (use service layer)10. 快速决策流程
决策树
新项目技术栈选型
│
├─ 有 AI/LLM 功能？
│ ├─ 是 → 加入 Vercel AI SDK (TS) 或 LangChain (Python)
│ │ 加入 Langfuse 可观测性（第一天）
│ └─ 否 → 继续下一步
│
├─ 主要语言？
│ ├─ TypeScript → Next.js 全栈 组合 A
│ └─ Python → FastAPI + LangChain 组合 B
│
├─ 需要多端？
│ ├─ 国内小程序 → Taro 4
│ ├─ 海外移动 → Expo
│ └─ 桌面 → Tauri 2
│
└─ 部署目标？
├─ 简单上线 → Vercel
├─ 边缘/全球 → Cloudflare Workers
└─ 长时任务 → Railway决策记录规范（ADR 简版）
每次重要技术栈决策在项目 docs/decisions/ 记录：
markdown
# ADR-001: 选择 Vercel AI SDK 替代直接调用 OpenAI SDK
**日期**: 2026-01-15
**状态**: 已采纳
**背景**: 项目需要支持 OpenAI 和 Anthropic 双模型
**决策**: 使用 Vercel AI SDK 统一接口
**理由**: 统一 streaming 接口，内置 React hooks，减少模型切换成本
**风险**: 依赖 Vercel 生态，版本升级需关注 breaking change技术栈健康度定期检查
每季度审计：
- 各依赖是否仍在 AI 训练数据覆盖良好的版本（检查 changelog）
- LLMOps 面板中幻觉率超过 15% 的模块是否需要换更稳定的框架
- 新框架（B 级晋升 A 级）是否值得迁移