在 AIGC 浪潮席卷开发领域的今天， “会接 AI API”已经不再是核心竞争力，真正拉开差距的，是你是否具备构建可扩展、可维护、可持续演进的全栈工程能力。
本文将以 Notes AI 项目为背景，不纠结具体业务实现，而是聚焦于：
一个现代 AI 全栈项目，底层工程化与 UI 架构应该如何设计？
项目蓝图：Notes AI
Notes AI 是一个现代化的 AI 驱动内容平台，核心模块包括：
- 身份认证：登录 / 注册 / 权限控制
- 文章系统：内容发布、管理与分发
- AIGC 能力：AI 辅助写作、内容生成
- 后端架构：基于 NestJS 的高内聚 API 服务
功能并不复杂，但工程复杂度并不低。
真正决定项目质量的，并不是功能列表，而是它的基础设施选择。
UI 新范式：为什么选择 Shadcn UI？
在 Notes AI 中，我们并没有选择 Ant Design、MUI 等“传统组件库”，而是选择了 Shadcn UI。
Shadcn UI 本质是什么？
一句话概括：
Shadcn UI 不是组件库，而是组件源码生成器。
它和传统 UI 库的核心差异在于：
| 传统组件库 | Shadcn UI |
|---|---|
| npm install 引入黑盒组件 | CLI 拉取源码到本地 |
| 覆盖样式成本高 | 直接改源码 |
| 依赖版本升级风险 | 组件完全由你掌控 |
| 往往体积不可控 | 用多少，引入多少 |
源码所有权，才是真正的自由
当你执行：
npx shadcn@latest add button
Shadcn 会做一件非常“反直觉”的事情：
把 Button 组件的源码直接拷贝进你的项目中
通常路径是：
src/components/ui/button.tsx
这意味着：
- 没有“库升级破坏样式”的风险
- 可以随意修改 Tailwind 样式
- 可以改交互逻辑、加埋点、加权限
组件不再是“外部依赖”，而是你工程的一部分。
这对中大型项目来说，价值非常大。
路径别名：Shadcn 能好用的前提条件
Shadcn 强烈依赖路径别名（Alias） ，否则组件引入会迅速失控。
没有别名时的灾难
import { Button } from '../../../../components/ui/button'
使用别名后的理想状态
import { Button } from '@/components/ui/button'
这不仅是“写得短”，而是：
- 项目结构更稳定
- 重构成本更低
- 组件层级更清晰
而这一步，Vite + TypeScript 必须同时配置。
工程化基石：Vite 配置深度解析
vite.config.ts 的核心职责
Vite 的配置本质上只有两件事：
- 插件系统（plugins）
- 模块解析规则（resolve）
plugins：构建能力扩展
plugins: [
react(), // React JSX 支持
]
- React / Vue 插件是必需的
- Tailwind 通常通过
postcss.config.js配置，而非 Vite 插件
resolve：模块解析规则
resolve: {
alias: {
'@': path.resolve(__dirname, './src'),
},
extensions: ['.js', '.ts', '.jsx', '.tsx', '.json'],
}
重点只有一个：
把 @ 映射到 src 目录
❗为什么需要 @types/node？
这里使用了：
__dirnamepath.resolve
它们都属于 Node.js API，而不是浏览器 API。
TypeScript 默认并不认识这些类型，因此必须安装：
npm i -D @types/node
这一步的本质是：
让 TS 在“Node 环境”下正确理解 vite.config.ts
这是非常容易被忽略，但在面试中很加分的细节。
TypeScript 路径映射：tsconfig.app.json
很多人只配了 Vite，然后疑惑：
“为什么编辑器还在报错？”
原因是：
Vite 负责构建，TypeScript 负责类型系统
必须同步配置 tsconfig
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["src/*"]
}
}
}
关键结论
vite.config.ts→ 运行时解析tsconfig.app.json→ 编译期 / IDE 智能提示
二者必须一致，否则一定踩坑。
npx：被严重低估的工程利器
1. npx 是什么？
npx 是 npm 自带的命令行工具，核心作用是：
无需全局安装，直接执行 npm 包中提供的 CLI 命令
它会在需要时临时下载对应包，执行完成后不干扰本地或全局环境。
2️. 为什么现代项目离不开 npx？
- 不需要全局安装
- 用完即走，不污染环境
- 默认使用最新版本
- 非常适合脚手架和生成器
3️. Shadcn CLI 的最佳拍档
npx shadcn@latest init
该命令会：
- 初始化
components.json - 配置 Tailwind 风格
- 设置路径别名
- 确定组件生成目录
这是 Shadcn 体系的入口，而不是可选步骤。
总结：这不是技术堆砌，而是工程思想
Notes AI 项目背后体现的，并不是某个炫酷技术点，而是一整套现代工程化思维：
- NestJS：提供稳定、可扩展的后端架构
- Vite：通过精细化配置，提供极速 DX
- Shadcn UI：用“源码所有权”取代黑盒组件
- Tailwind CSS：原子化样式，避免 CSS 失控
- npx：让工具链更轻、更干净
真正优秀的 AI 应用，拼到最后，拼的是工程能力。
