Vite + TypeScript 工程初始化：配置取舍与踩坑排查顺序

一、为什么不用脚手架一把梭

很多教程第一步就是 npm create vite@latest，然后跑起来就结束了。但真到团队协作，麻烦往往出现在脚手架照顾不到的地方：依赖装不上、锁文件被忽略、构建产物和开发环境不一致。

这篇文章记录一次 Vite + TypeScript 项目从零到可以预览的完整过程，重点放在踩坑和取舍，而不是hello world。

二、目录与配置的取舍

1. 锁文件必须进版本库。package-lock.json 是复现构建的前提。CI 上用 npm ci 而不是 npm install——前者严格按锁文件安装，装出来的依赖树和本地一致。

2. tsconfig 分层。浏览器侧代码（src/）和 Node 侧配置（vite.config.ts）的运行环境完全不同，硬塞进一个 tsconfig 会出现"能编译但类型不对"的情况。推荐拆成 tsconfig.json + tsconfig.node.json，用 references 关联：

• tsconfig.json 负责 src，moduleResolution 用 bundler；
• tsconfig.node.json 负责构建脚本，module 用 ESNext、composite 开启才能被引用。

3. 严格模式早点开。strict、noUnusedLocals、noUnusedParameters、noFallthroughCasesInSwitch 建议一开始就打开。项目大了再开，改造成本会指数上升。

三、依赖安装失败的排查顺序

"装不上"其实分三种情况，按下面顺序排最省时间：

• 网络层：先确认 registry 可达，必要时换镜像源；注意有的企业网络会拦截 node-gyp 下载的二进制。
• 原生模块层：这类包（如 esbuild、sharp）安装时会下载对应平台的预编译二进制，走的是独立 CDN，镜像源换了也没用。要单独配置二进制镜像或走代理。
• 版本层：Node 版本太新，包的安装脚本可能用了已移除的 API。此时不要急着降级 Node，先看有没有官方修复版本，或者用 --ignore-scripts 先装依赖再手动补二进制。

四、dev server 的一个常见假死

开发服务器启动时报 The service was stopped: write EPIPE，通常不是代码问题，而是子进程（esbuild 的 service process）被中断了——比如上一次进程被强杀、或者同时起了两个 dev server 抢同一个端口。

• 先确认没有残留的 node 进程占着端口；
• 删掉 node_modules/.vite 缓存目录再启动；
• 如果要在 IDE 内置浏览器里预览，把 open 设为 false，避免它反过来弹出外部浏览器。

五、一个够用的 vite.config.ts

不需要一开始就上插件全家桶。最小可用配置其实只有三件事：框架插件、路径别名、开发服务器行为。

• resolve.alias 把 @ 指到 src，避免出现 ../../../ 这种路径；
• server.port 固定端口，方便团队统一调试地址；
• build.sourcemap 生产环境按需开启，能显著影响体积和排查体验的取舍。

六、小结

工程初始化这件事，"能跑起来"和"能长期维护"之间的差距，几乎全在配置文件里。先把锁文件、tsconfig 分层、严格模式这三件小事做对，后面省下的返工时间会远超投入。