前端配环境配到崩溃？这个一键脚手架让我少掉了一把头发

我要讲一个你可能经历过的故事。

某个周一早上，产品找你说："我们要做一个新项目，本周五能出第一版吗？"

你说："没问题，这个功能不复杂。"

然后打开终端，开始配环境。

一个现实的周一早上

create-react-app？已经半废了，不用。Vite 直接初始化？好，装上。然后 TypeScript，装上。然后路由，用 React Router 还是 TanStack Router？选了半天，TanStack Router。好，装上配置，但路由类型怎么搞......

午饭后继续。接口请求用 Axios 还是 React Query？React Query 更现代，装上。但 QueryClient 配在哪？翻文档。然后样式，Tailwind 吧，装上，PostCSS 配置再弄一下。

下午，代码质量工具。ESLint，装上。Prettier，装上。然后两个打架了，查 StackOverflow，用 eslint-config-prettier 协调。Git hooks，Husky，lint-staged，commitlint，一个一个装，一个一个配。

到了晚上，终于能 pnpm dev 跑起来了。

周五？先把环境配好再说吧。

TanVite 是什么

这就是为什么我觉得 TanVite 值得专门写一篇文章介绍。

一句话：它是一个 React 19 的生产级脚手架，把上面那一堆事全帮你做完了。

perl 复制代码

npm create tanvite@latest my-app
cd my-app
pnpm install
pnpm dev

四条命令，打开 http://localhost:4319，你会看到一个完整运行的应用，带着：

React 19 + Vite 5 + TypeScript
TanStack Router（文件路由）
TanStack Query（数据请求）
Tailwind CSS + shadcn/ui 工具
Biome（lint + format）
Vitest + Playwright（单元测试 + E2E 测试）
MSW + Prism（Mock 服务）
Husky + commitlint（Git 提交规范）
GitHub Actions CI
......

不是"装了但没配"，是真的配好了，能直接用的那种。

让我最惊喜的几个细节

1. OpenAPI 自动生成代码，这不是魔法

前后端对接接口是个慢性病。接口文档过时了，字段名拼错了，类型对不上......这些 bug 往往在联调时才发现，整个链路追下来浪费的时间是一个函数（然后程序员互相甩锅）。

TanVite 内置了 Orval 的 OpenAPI 工作流：

ini 复制代码

# 在 .env.local 里配你们后端的 Swagger 地址
OPENAPI_SCHEMA_URL=http://your-backend/api-docs

# 一条命令，自动生成：
# - 所有接口的 TypeScript 类型
# - 封装好的请求函数
# - React Query 的 useQuery/useMutation hooks
# - MSW Mock 处理函数
pnpm openapi:generate

后端把接口定义好（写 Swagger），前端跑一次生成命令，所有代码就出来了。

后端改了字段名？重新生成，TypeScript 编译器会告诉你哪里要改，不需要靠记忆和文档。这种感觉，就像从手工制砖突然用上了砖机。

2. Mock 体系想得很周全

bash 复制代码

pnpm dev:mock     # Vite + MSW，浏览器级别拦截接口
pnpm openapi:mock # 启动独立的 Prism Server（端口 4010）

这两种 Mock 方式解决的是不同场景：

MSW：适合"我想快速看看 UI 长啥样"，不需要开额外进程
Prism：适合"需要真实 HTTP 交互"，比如测试前端的 loading 状态、网络错误处理

后端还没写完、你也不想等？两种 Mock 随时顶上。

3. Biome 真的快到让人感动

以前用 ESLint + Prettier，在大项目里保存一下文件格式化要等 1-2 秒，pre-commit 跑完 lint 要等 10 几秒。时间长了，你会开始怀疑自己的人生选择。

Biome 用 Rust 写的，承担了 lint 和 format 两件事，速度快了不是一点半点。在 TanVite 里只有一个 biome.json，没有 .eslintrc.js、.prettierrc 来来回回那一套。

保存，秒格式化。提交，秒通过检查。开发体验好很多。

4. TanStack Router 的类型是真的香

用过 React Router 的人可能都有这个经历：路由参数拿出来是 string | undefined，自己要转类型，一不小心就 undefined is not a number。

TanStack Router 从设计之初就是 TypeScript-first，路由参数、搜索参数（query string）全都有完整的类型推断：

javascript 复制代码

// 路由定义时就声明类型
const Route = createFileRoute('/product/$id')({
  validateSearch: (search) => ({
    page: Number(search.page ?? 1),
    sort: search.sort as 'asc' | 'desc' ?? 'asc',
  }),
})

// 组件里用的时候，类型是对的
const { page, sort } = Route.useSearch()
// page: number, sort: 'asc' | 'desc'
// 不是 string，不需要手动转换

IDE 会告诉你哪些参数可以传，传错了直接报错。这是"类型安全"真正体现价值的地方。

AI 协作这件事，TanVite 做了一个很有意思的尝试

bash 复制代码

.agents/skills/     # 给 Codex（GitHub Copilot）的技能包
.claude/skills/     # 给 Claude Code 的工作流指引
.claude/commands/   # OpenSpec 快捷命令

这些文件夹里存的是什么？是项目的规范------设计规范、代码风格、测试要求、Git 工作流。

这个设计背后的逻辑是：现在大家都在用 AI 工具写代码，但 AI 不了解你的项目上下文，给出的建议往往是泛泛的通用写法，不符合团队规范，还得人工修改。

TanVite 把规范写进这些技能包，AI 工具（Claude Code 或者 Codex）在生成代码的时候会自动读取这些上下文，输出的东西更贴合项目实际情况。

"与其让人去监督 AI，不如先把规范教给 AI。"

这个思路我觉得很超前，也很实用。

OpenSpec：把需求文档也纳入版本控制

这是一个稍微高阶一点的功能，但我觉得值得一提。

TanVite 内置了 OpenSpec，一套轻量的规格管理工作流：

bash 复制代码

openspec/
├── changes/    # 进行中的需求变更提案
├── specs/      # 基准功能规格
└── config.yaml

csharp 复制代码

pnpm openspec:new feat/用户资料页重设计
# 在 openspec/changes/ 里创建变更提案

很多团队的需求文档活在飞书或者 Notion 里，和代码库完全脱节。OpenSpec 的思路是把功能规格和变更提案也放进代码仓库，和代码一起做版本控制。

三个月后回来看这段代码是干嘛的？找对应的 openspec change，一清二楚。

项目结构是清晰的

bash 复制代码

src/
├── lib/
│   ├── api/          # OpenAPI 生成的代码放这里
│   ├── query-client.ts
│   └── utils.ts      # cn() helper
├── mocks/            # MSW 配置
├── routes/           # 文件路由，新建文件自动注册
└── types/            # 全局类型定义

结构约定很清晰，新同学接手项目知道该把代码放哪。这种"约定"的价值，在团队大了之后会越来越明显。

一些实际的数字

脚本命令 ：pnpm routes:generate、pnpm openapi:generate、pnpm dev:mock......17 个常用脚本，覆盖开发、测试、构建、预览的全流程
测试层次：单元测试（Vitest）+ E2E 测试（Playwright），两层都有配置好的
CI 流程：push 自动触发 lint 检查 + 单元测试，PR 才能合并
Node 要求：Node.js 20+，pnpm 10+，要求不高

怎么上手

新建项目（推荐方式）：

perl 复制代码

# 基础版
npm create tanvite@latest my-app

# 完整版（包含 OpenSpec、OpenAPI、Playwright、AI 技能包等）
npm create tanvite@latest my-app -- --preset full

只是想看看代码学习：

直接克隆源码仓库：github.com/YangsonHung...

最后

我不是说配环境这件事以后就不用管了------每个项目都有自己特殊的需求，总有些地方要自己动手。

但有一套经过深思熟虑的基础在，你从第一天开始就站在了一个更高的起点：不用从零考虑技术选型，不用从零配 lint 和测试，不用从零写 GitHub Actions。

省下来的时间，写功能它不香吗？

🔗 项目地址：github.com/YangsonHung...

🌐 在线 Demo：yangsonhung.github.io/tanvite/

如果觉得有用，欢迎给项目点个 Star ⭐ 也欢迎在评论区说说你们团队是怎么解决工程化问题的。