如果你觉得 Vite 工程化配置就是往vite.config.ts里塞几个参数那大概率会在项目跑到中途的时候被各种诡异问题干懵。我最近把一个跑了大半年的模拟项目X——一个典型的中后台管理系统——从配置到构建链路完整梳理了一遍重点覆盖环境变量、代码规范、性能优化三条线。折腾完之后一个很深的感受是Vite 上手快是快但真正的工程化难点从来不在启动速度本身而在多环境切换、多人协作、产物控制这些看起来琐碎、实际上每天都在影响开发体验的细节上。这篇就是把整个配置过程完整记录下来包括我做过的方案选型、踩进去又爬出来的坑以及最终沉淀下来可以直接复用的配置。1. 环境变量配置先从 import.meta.env 说起很多项目在环境变量这块都处于“能跑就行”的状态接口地址写死在代码里上线前手动改一遍或者顺手装了dotenv然后在 Vite 里混用。这两种做法短期看着省事一碰到多环境部署就全是隐患。Vite 其实自带了一套完整的环境变量机制核心就是import.meta.env只是不少人对它的了解停留在“知道有这么个东西”。1.1 内置变量与自定义变量需要先搞清楚的基础规则import.meta.env是 Vite 在编译时注入到源码里的全局对象使用方式和普通对象一样但里面的值会在构建时被静态替换。它自带几个内置变量我整理了一张表变量名含义MODE当前运行模式例如development、production或者是通过--mode指定的任意值DEV是否处于开发模式等价于MODE developmentPROD是否处于生产模式等价于MODE productionBASE_URL部署基础路径对应base配置项SSR是否在服务端渲染模式下运行源码里可以直接这样用const apiUrl import.meta.env.DEV ? /api : https://api.example.com开发模式下走本地代理生产模式走线上域名这是最常见的用法。自定义变量方面Vite 的规则是只有以VITE_前缀开头的变量才会暴露到import.meta.env中。比如你在.env文件里写了VITE_API_URL/api VITE_APP_TITLE模拟项目X SECRET_KEYdo-not-leak那么在源码里能访问到的是import.meta.env.VITE_API_URL和import.meta.env.VITE_APP_TITLESECRET_KEY永远拿不到。这个“拿不到”不是缺点反而是安全设计。客户端环境变量本质上都会被打包进产物任何被import.meta.env引用的值浏览器都能看到。Vite 用前缀做一个强制隔离提醒你哪些东西可以放前端哪些东西必须留在服务端。就好比家里每个房间装了不同的锁Vite 只会把你配了钥匙VITE_前缀的房间开放给前源码其他房间在构建阶段就被屏蔽了。1.2 .env 文件拆分与优先级多环境不再手改代码环境变量不能只有一套开发、测试、预发布、生产每个环境都有各自的接口地址和开关配置。Vite 约定了一套文件命名规范按 mode 自动加载文件作用.env所有环境共享的通用配置.env.development开发环境vite/vite dev加载.env.production生产环境vite build加载.env.local本地覆盖所有环境都会加载不提交到 git.env.development.local开发环境的本地覆盖优先级最高.env.production.local生产环境的本地覆盖优先级最高举个例子项目里可以这样拆分# .env VITE_APP_TITLE模拟项目X VITE_APP_VERSION1.0.0# .env.development VITE_API_URL/api VITE_MOCK_ENABLEDtrue# .env.production VITE_API_URLhttps://api.example.com VITE_MOCK_ENABLEDfalse加载优先级从高到低是.env.[mode].local.env.[mode].env.local.env。记住一个要点越“具体”的文件优先级越高local后缀永远是最顶层的覆盖层这样每个开发者可以在不污染公共配置的前提下用自己的本地配置覆盖默认值。除了这些.env文件之外有时还需要在vite.config.ts里读取环境变量来做配置判断。Vite 提供了loadEnv方法import { defineConfig, loadEnv } from vite export default defineConfig(({ mode }) { const env loadEnv(mode, process.cwd(), ) return { server: { proxy: { /api: { target: env.VITE_PROXY_TARGET || http://localhost:8080, changeOrigin: true, }, }, }, } })这里第三个参数传很关键表示不过滤前缀把.env里的所有变量都读出来。如果不传默认只会读取VITE_前缀的变量像我上面的VITE_PROXY_TARGET虽然带了前缀所以没问题但如果某个变量没有前缀且又想在配置里使用就必须传空字符串。1.3 自定义变量的坑类型声明与安全性环境变量在vite.config.ts和源码里的使用方式不同定义了一个变量不等于编辑器不会报错。默认情况下import.meta.env的类型是 Vite 内置的ImportMetaEnv只包含通用属性。你自定义了一个VITE_API_URL在源码里写import.meta.env.VITE_API_URL时TypeScript 会提示这个属性不存在。解决方式是在项目根目录维护一个env.d.ts/// reference typesvite/client / interface ImportMetaEnv { readonly VITE_API_URL: string readonly VITE_APP_TITLE: string readonly VITE_APP_VERSION: string readonly VITE_MOCK_ENABLED: boolean } interface ImportMeta { readonly env: ImportMetaEnv }加上类型声明之后编辑器能自动补全还能避免手滑写错变量名这个步骤强烈建议加上。安全方面的坑必须单独说任何写入VITE_前缀变量的值都会被打包进前端产物里。我之前见过一个项目为了图省事把数据库连接地址和账号密码写进了VITE_变量虽然代码里的逻辑没直接展示但只要打开浏览器开发者工具看打包后的 JS所有值都看得一清二楚。前端环境变量只适合放公开配置接口地址、埋点开关、功能开关、文案配置。真要涉及密钥、token、签名这类敏感信息必须放到服务端环境变量里通过接口下发。还有一个小坑修改了.env文件之后本地 dev server 必须重启才能生效。Vite 虽然热更新很快但环境变量的加载发生在启动阶段不是模块依赖。我之前习惯性地改了.env.development后等热更新等了半天发现变量没变重启之后才正常。如果你在 CI 环境里改了环境变量后构建结果不对也优先检查是不是没清缓存后面性能优化部分会详细说.vite缓存目录。2. 代码规范落地在“自由”中建立秩序Vite 项目大多是 TypeScript很多人觉得有 TS 就够规范了。实际上 TS 只保证类型不报错控制不了代码长什么样单引号还是双引号、分号要不要、缩进有多大、接口命名是IXxx还是XxxProps这些全靠人肉统一。一个人写还好一旦团队超过三个人git log 里就会出现大量“格式化冲突”提交。2.1 ESLint 配置新版 Flat Config 实践ESLint 8.x 时代大家用.eslintrc.json写 extends 和 rulesESLint 9 之后全面转向 flat configeslint.config.js。Vite 项目里我建议直接用新版方式配置避免将来重复迁移。我最终沉淀的 ESLint 配置长这样// eslint.config.js import js from eslint/js import tseslint from typescript-eslint export default tseslint.config( { ignores: [dist/**, coverage/**, node_modules/**], }, js.configs.recommended, ...tseslint.configs.recommended, { rules: { typescript-eslint/no-unused-vars: [error, { argsIgnorePattern: ^_ }], no-undef: off, }, } )需要解释几个点。tseslint.config()是typescript-eslint提供的封装函数它可以把多个配置段合并成最终配置省去了手动处理 ESLint 9 扁平结构的繁琐。js.configs.recommended是 JS 的基础推荐规则...tseslint.configs.recommended是 TS 的推荐规则。如果你用的是 React还要额外引入eslint-plugin-react-hooks用的是 Vue则引入eslint-plugin-vue的 flat 配置。no-undef: off这一行必须说明白TS 编译器本身已经能检查未定义变量而 ESLint 的no-undef规则对 TS 类型声明会有误报。比如类型定义里的any、全局类型、接口类型都可能被no-undef当成“未定义变量”。更合适的做法是交给 TS 的no-undef语义去处理ESLint 这边只做语法规范。2.2 Prettier 负责格式ESLint 负责质量分工要清楚ESLint 和 Prettier 的职责很容易混淆。我的经验是ESLint 管代码质量Prettier 管代码格式。代码质量是“有没有 bug、有没有明显反模式”代码格式是“标点、缩进、换行、引号是否统一”。两件事混在一起配置会变得极其拧巴因为格式化规则跟语法规则互相干扰一会儿这个报错一会儿那个报错。我的prettier.config.js配置// prettier.config.js export default { semi: false, singleQuote: true, trailingComma: all, printWidth: 100, tabWidth: 2, endOfLine: lf, }semi: false表示不写分号singleQuote: true表示一律单引号。这些是纯个人偏好关键是团队统一。trailingComma: all会把多行对象和数组的末尾也加上逗号这样以后增删字段时不会产生一行改动的误 diff。实际工作中我习惯于在vscode里配置保存时自动格式化{ editor.defaultFormatter: esbenp.prettier-vscode, editor.formatOnSave: true, editor.codeActionsOnSave: { source.fixAll.eslint: explicit } }这样写着写着代码就自动规范了不用最后手动跑一遍命令。团队项目里建议再放一个.editorconfig统一缩进和换行符。不同操作系统下默认换行不同Windows 是 CRLFmacOS/Linux 是 LF没有.editorconfig的话每个文件的换行符可能乱七八糟git diff 也会被换行符污染。2.3 提交前自动检查husky lint-staged 把关最后一公里规范和格式化能自动干活但人总是会忘。最终防线我交给了huskylint-staged在 git commit 这个入口做强制检查。也就是说代码只有通过检查才能提交进版本库从源头避免“等大家拉下来才发现风格不一样”的局面。安装和初始化pnpm add -D husky lint-staged npx husky inithusky init会自动生成.husky/pre-commit文件把里面的默认内容改成执行lint-staged# .husky/pre-commit npx lint-staged然后在package.json里配置 lint-staged 的作用范围{ lint-staged: { *.{ts,tsx,vue,js,jsx}: [ eslint --fix, prettier --write ] } }这样每次提交前只会对本次暂存区里的文件做检查和修复而不是全量检查整个项目。这一点很关键老项目里历史遗留的格式问题特别多如果一上来全量检查你第一次提交可能被迫改几十个文件commit 记录里全是格式改动根本没法 review。注意husky在团队协作时有一个很隐蔽的坑——新成员 clone 项目后执行pnpm install时如果使用包管理器版本不一致或安装脚本没触发.husky目录不会自动生效。所以初始化完husky后建议在package.json里确认prepare脚本存在{ scripts: { prepare: husky } }另外git commit --no-verify可以绕过钩子。这个命令我建议仅在紧急情况下使用一旦变成习惯整个代码规范防线就形同虚设了。3. 性能优化让构建更快、产物更瘦Vite 拿“快”作为招牌默认启动确实够快。不过项目跑久了、依赖越装越多构建效率和产物体积都会慢慢变差。性能优化这部分我理解要从两个维度看一个是“开发体验”维度也就是 dev server 启动、页面热更新、完整构建的耗时另一个是“线上体验”维度也就是最终产物的 chunk 体积、首屏加载数据量。3.1 依赖预构建为什么 Vite 快什么时候需要手动干预Vite 开发模式下之所以感觉不到上千个依赖的加载时间靠的是 esbuild 预构建。简单说Vite 会把node_modules里的第三方依赖用 esbuild 统一打包成 ESM 格式然后存到node_modules/.vite目录下做缓存。第一次启动时进行预构建之后只要依赖没变就直接读缓存所以再次启动只需要毫秒级时间。大部分情况这个机制是透明的但有两个场景需要手动配置optimizeDeps。场景一是某些依赖不在入口文件的静态引用链上而是在运行中被动态import()进来的Vite 的依赖扫描可能发现不了导致页面第一次真正加载这个依赖时出现二次预构建的卡顿。解决方式是在optimizeDeps.include里显式声明export default defineConfig({ optimizeDeps: { include: [lodash-es, axios], }, })场景二是某些依赖体积很大但很少用预构建会导致启动缓存体积膨胀甚至首次启动变慢。如果确认某个依赖不需要预构建可以在exclude里排除export default defineConfig({ optimizeDeps: { exclude: [my-config/private-lib], }, })改了optimizeDeps之后记得重启 dev server。如果遇到各种奇怪的依赖加载报错可以直接删掉node_modules/.vite目录或者执行npx vite --force强制重新预构建。这个“强制重来”的命令在排查循环依赖、版本混用问题时几乎百试百灵。3.2 产物分析先找出谁在拖后腿再谈优化构建产物增大之后vite build会弹出 chunk 超过 500KB 的警告。很多人的第一反应是把chunkSizeWarningLimit调大比如调到 1000 甚至直接关掉。我的建议是不要急着调这个值警告是对你的提醒直接关掉等于掩盖问题。正确操作是先跑一轮产物分析看看究竟是谁把 chunk 撑大的。生产环境构建之后用rollup-plugin-visualizer生成可视化报告pnpm add -D rollup-plugin-visualizer在vite.config.ts里配置import { visualizer } from rollup-plugin-visualizer export default defineConfig({ plugins: [ visualizer({ open: true, gzipSize: true, brotliSize: true, }), ], })构建完会自动打开一个 HTML 报告里面的矩形块大小代表各个依赖的体积。拿模拟项目X来说当时构建后最大的 chunk 到了 900 多 KB点开一看一个体积庞大的图表库被完整打进了业务 chunk。这个图表库只在三个页面用到了而且只用到了折线图和柱状图但项目里是import * as整包引入的。处理方式是改成按需引入只注册用到的模块。一番调整后这个 chunk 从 900 多 KB 降到 200 多 KB首屏加载压力小了很多。实际操作时任何体积大的第三方依赖都值得做一次按需引入评估这比任何 Vite 配置调优的收益都直接。3.3 路由懒加载与拆包策略让首屏只加载该加载的中后台管理系统普遍是几十个路由页面如果所有页面都打包在一个 chunk 里首屏就要把所有页面的代码全下载下来。这完全没有道理用户明明只打开了登录页和首页为什么要加载报表页、权限管理页的代码路由级别懒加载是最应该做、收益也最明显的优化。Vue 项目里把路由组件改成动态引入const routes [ { path: /dashboard, name: Dashboard, component: () import(/pages/Dashboard.vue), }, { path: /reports, name: Reports, component: () import(/pages/Reports.vue), }, ]React 项目里用React.lazyconst ReportsPage React.lazy(() import(/pages/ReportsPage)) function App() { return ( React.Suspense fallback{PageLoading /} Routes Route path/reports element{ReportsPage /} / /Routes /React.Suspense ) }除了路由懒加载还需要在构建阶段配置manualChunks做手动拆包export default defineConfig({ build: { rollupOptions: { output: { manualChunks: { react-vendor: [react, react-dom, react-router-dom], ui-components: [antd], charts: [echarts/core], }, }, }, }, })拆包的逻辑是把长期不变、体积较大的第三方依赖单独拆出来。浏览器会按 URL 缓存这些 chunk依赖不升级chunk 内容不变用户下次访问就能直接命中缓存不需要重新下载。但如果把第三方依赖和业务代码混在一起业务代码每次发布都会导致整个大 chunk 失效缓存优势就没了。有一点要提醒manualChunks的拆包也不是越细越好。chunk 数量过多会导致 HTTP 请求数量增加反而拖慢加载速度。一般控制在 5~10 个公共 chunk 就差不多了。3.4 构建加速的几个实战细节除了产物体积构建本身的耗时也影响团队体验。我整理了几个在实际项目中确实有效的小优化按实施成本从低到高排列。第一精简插件。Vite 生态有不少提升开发体验的插件但插件越多构建越慢。检查一遍plugins数组确认每个插件都是必要的比如某插件只会在 dev 模式下生效那就可以用apply限定环境别让它在 build 阶段空跑。第二合理设置build.target。默认值modules已经支持了较新的浏览器特性。如果你把target降到es2015需要做更多转译产物会明显变大、构建也更慢。除非产品确实要考虑上古浏览器否则保持默认就好。这里的关键是不要为了“兼容性”无脑降级很多兼容目标是伪需求真正要覆盖的设备列表应该由用户数据说了算。第三使用assetsInlineLimit控制小图片。Vite 会把低于阈值的小图片转成 base64 内联进代码减少 HTTP 请求。默认值是 4KB4096 字节一般够用。不要调太高否则稍大一点的图片都变成 base64反而会让 HTML 和 JS 文件体积膨胀传输效率更差。第四缓存策略。本地开发时node_modules/.vite是缓存目录不要随意清掉。CI 环境里构建时要在前后两次构建之间缓存node_modules和~/.cache相关目录。模拟项目X的构建流程在缓存掉线的时候大约 8 秒缓存生效后降到 4 秒左右。这种时长差异不算巨大但胜在稳定不会动不动因为冷启动失败导致发布流水线卡住。4. 配置过程中的常见问题与排查实录配置工程化的真实写照大部分时间不是写配置而是在排查“为什么配置了没生效”。下面这几个问题是 Vite 项目里我遇到最多、也最有共性的整理成一份速查笔记。4.1 环境变量不生效从这三个地方排查下表总结了我在实践中遇到的环境变量问题及对应解法现象原因解决办法修改.env后import.meta.env的值不变dev server 没重启环境变量是启动时加载的重启 dev server源码里访问自己的变量返回undefined变量名没有VITE_前缀给变量加上前缀或者用loadEnv仅限配置文件里使用编辑器 TS 报“属性不存在”env.d.ts里没声明自定义变量类型补全ImportMetaEnv接口声明生产环境和本地环境拿到的值不一样.env.[mode]和.env.local的优先级覆盖关系没搞清楚按优先级链检查是否被覆盖必要时在代码里临时console.log打印MODE和DEV线上构建后某个变量是空的CI 环境没有正确注入.env.production或环境变量在 CI 构建日志里确认 env 文件是否存在注意.env.local默认不进 gitCI 里不会自动有这个文件一个容易忽略的点是.env.local只存在于本地不会提交到 git。如果你把某个环境变量只写在.env.local里同事拉代码时会发现这个变量缺失构建直接挂掉。解决办法是公共配置放到.env和.env.[mode].env.local只用来放置属于个人本地环境的覆盖项比如本地调试用的 mock 开关、本地代理地址。4.2 ESLint 和 TypeScript 规则冲突怎么破ESLint 和 TS 的冲突最常见的场景是no-undef误报。比如在 TS 文件里定义了一个接口然后在下方代码里用了这个接口名ESLint 的no-undef规则会认为这是“未定义变量”——实际上它是类型不是运行时变量。解决方式在于正确配置使用typescript-eslint的解析器后要关闭 ESLint 原生的no-undef规则或者说采用tseslint.configs.recommended这套专门为 TS 适配的规则集不要直接用js.configs.recommended里的所有规则。我的配置里写了no-undef: off原因就在这。还有一类冲突是 import 顺序。ESLint 的 import 规则和 Prettier 的排序逻辑有时会打架我建议不要在 ESLint 里配置 import 排序把它交给 Prettier 或者单独的排序工具处理。规则少一些、职责清晰一些配置反而更好维护。4.3 构建后 chunk 超大的排查路径vite build完成后弹出 chunk 超限警告完整的排查思路是这样的先不改chunkSizeWarningLimit直接用visualizer插件生成体积报告确认哪几块体积最大。看大体积块来自哪个依赖。如果是某个第三方库评估是否能按需引入、是否能换更轻量的库、是否真的被高频使用。看你的 chunk 拆分策略。第三方依赖是否打在了业务 chunk 里业务代码是否按照路由做了懒加载如果确认某个 chunk 大是因为它承载了完整的路由组件和依赖且这是合理业务形态这时再考虑调高chunkSizeWarningLimit到合理水平比如 1000KB而不是直接关掉。我在模拟项目X里踩过的具体问题一个业务页面密集使用了某 UI 组件库路由懒加载之后这个页面单独成为了一个 400KB 的 chunk。分析后发现该页面引入了组件库的全部样式和组件但实际只用到其中一小部分。调整成按需引用组件库的模块后页面的首屏加载耗时明显下降。拿工具说话别拍脑袋这是排查构建问题最有效的原则。4.4 沉淀一套可复用的工程化基座把环境变量、代码规范、性能优化这几块配置梳理完最后一步是把它变成可复用的“基座”而不是每次新建项目都重新踩一遍坑。我建议的落地方式是把以下文件沉淀为模板仓库的 baselinevite.config.ts基础构建配置、loadEnv环境判断、manualChunks拆包策略、optimizeDeps预构建声明eslint.config.jsprettier.config.js.editorconfig代码规范三件套.env/.env.development/.env.production环境变量文件的标准命名与内容结构.husky/pre-commitpackage.json的lint-staged配置提交前自动检查链路env.d.tsImportMetaEnv类型声明模板模板仓库里的配置不要只贴代码我习惯在关键位置写注释说明“为什么这么配”“什么场景调整它”这样新成员看一眼就能理解不会盲目模仿或随意改动。版本锁定也是个容易忽略的点。package.json里的 Vite、ESLint、typescript-eslint版本如果浮动可能过一阵子配置就失效了。我之前就遇到过typescript-eslint大版本升级后旧配置格式直接废弃项目一跑 eslint 就是一堆报错。模板仓库维护时尽量把核心工具链版本固定升级时单独走一遍验证流程。从环境变量到代码规范再到性能优化这三块配置的组合拳打完模拟项目X的开发链路终于算是稳定下来了代码提交前有规范检查构建产物体积可预期多环境切换不再手忙脚乱。最后分享一个小技巧在vite.config.ts里不要写那种“只有自己看得懂”的简略配置把每个字段后面的注释补全既方便后来人接手也方便项目跑了大半年后你自己回来看。配置工程化本身不产生业务价值但它决定了团队在长线迭代里每天省下多少时间、少踩多少无意义的坑。