vite-patterns

用途

vite-patterns 是面向 Vite 8+ 项目的构建工具与开发服务器实践参考。它覆盖配置文件编写、环境变量、代理设置、库模式、依赖预打包以及常见生产陷阱，适合在配置 vite.config.ts、搭建开发代理、优化构建产物或发布库时查阅。

主要能力

配置结构

文档给出基础配置与条件配置示例，使用 defineConfig 获得类型推断。常见配置项包括 root（项目根目录，默认 '.'）、base（部署资源公共基础路径，默认 '/'）、envPrefix（客户端可见环境变量前缀，默认 'VITE_'）、build.outDir（输出目录，默认 'dist'）、build.minify（默认 'oxc'，可选 'terser' 或 false）、build.sourcemap（默认 false）。条件配置中需注意 loadEnv 的用法。

插件

文档建议优先选用成熟插件，而非自行编写。列举的常用插件包括：@vitejs/plugin-react-swc（React 应用默认，基于 SWC）、@vitejs/plugin-react（仅在需要 Babel 插件时使用）、@vitejs/plugin-vue（Vue 3 SFC）、vite-plugin-checker（在工作线程运行 tsc 与 ESLint）、vite-tsconfig-paths（复用 tsconfig.json 路径别名）、vite-plugin-dts（库模式输出 .d.ts）、vite-plugin-svgr、rollup-plugin-visualizer（用 enforce: 'post'）、vite-plugin-pwa。文档特别提示：vite build 只转译不做类型检查，需配合 vite-plugin-checker 或在 CI 中运行 tsc --noEmit。

自定义插件宜先内联在 vite.config.ts 中，复用后再抽取。关键钩子包括 transform、resolveId + load（虚拟模块）、transformIndexHtml、configureServer、hotUpdate。虚拟模块使用 \0 前缀约定。

HMR

框架插件会自动处理 HMR，仅在编写自定义状态存储、开发工具或框架无关工具时直接使用 import.meta.hot。示例展示用 import.meta.hot.data 持久化状态（须修改属性而非重新赋值）、dispose 清理副作用、accept 接受自身更新。相关代码在生产构建中会被 tree-shaking 移除。

环境变量

Vite 按 .env、.env.local、.env.[mode]、.env.[mode].local 顺序加载，后者覆盖前者，*.local 文件应加入 gitignore。只有 VITE_ 前缀的变量暴露给客户端。可在配置中通过 loadEnv 访问。

文档强调 VITE_ 前缀不是安全边界：任何 VITE_ 变量都会在构建时静态内联进客户端产物，压缩、base64 编码或关闭 source map 都无法隐藏。机密信息必须放在服务端。loadEnv 的第三个参数若传空字符串会加载全部环境变量（包括服务端机密），应显式传入前缀列表。生产 source map 会泄露源码，除非上传至错误追踪服务，否则应保持关闭。

开发服务器代理

server.proxy 支持字符串简写与对象配置，对象形式可设置 target、changeOrigin、rewrite，WebSocket 代理需加 ws: true。

构建优化

手动分包通过 build.rolldownOptions.output.manualChunks 实现，支持对象形式（按包分组）与函数形式（启发式拆分）。

性能

文档指出 barrel 文件（目录下的 index.ts 重新导出全部内容）是官方文档标记的首要开发服务器性能问题，应直接导入具体文件。显式书写导入扩展名可避免多次文件系统检查。server.warmup.clientFiles 可预热热点路由。排查慢速开发服务器可用 vite --profile 生成 .cpuprofile，再用 Speedscope 分析。

库模式

发布 npm 包时使用 build.lib。两个关键点：不会自动输出类型（需加 vite-plugin-dts 或单独运行 tsc --emitDeclarationOnly）；peer 依赖必须 external 化，否则会被打包进库并导致使用方运行时重复。

SSR 外部依赖

文档建议多数应用直接使用 Nuxt、Remix、SvelteKit、Astro 或 TanStack Start，而非手写 createServer({ middlewareMode: true })。作为框架使用者通常调整的是 ssr.external、ssr.noExternal、ssr.target。

依赖预打包

optimizeDeps 支持 include（强制预打包重依赖或 CJS 依赖）、exclude（须为合法 ESM）、force（忽略缓存重新优化，用于临时调试）。

使用方式

文档以代码示例形式提供配置片段、插件用法、环境变量读取、代理设置、分包、库模式与预打包等写法，并附有快速参考表将常见模式与适用场景对应。文档未提供安装命令或独立的 CLI 使用流程。

适用场景

配置 vite.config.ts / vite.config.js；设置环境变量或 .env 文件；配置开发服务器 API 代理；优化构建输出（分包、压缩、资源）；用 build.lib 发布库；排查依赖预打包或 CJS/ESM 互操作问题；调试 HMR、开发服务器或构建错误；选择或排序 Vite 插件。

常见陷阱与限制

开发与构建行为不一致：开发用 esbuild/Rolldown 转译，构建用 Rolldown 打包，CJS 库可能表现不同，部署前应用 vite build && vite preview 验证。
部署后旧 chunk 失效：Vite 无内置解决方案，可保留旧 dist/assets 文件或捕获动态导入错误并强制刷新。
Docker/容器：Vite 默认绑定 localhost，容器外无法访问，需设置 server.host: true，反向代理后需配置 hmr.clientPort。
Monorepo 文件访问：需通过 server.fs.allow 放开项目根目录以外的路径。
反模式：envPrefix 设为 '' 会暴露全部环境变量；在应用源码中使用 require()；把每个 node_module 拆成单独 chunk；库模式不 external peer 依赖；使用已弃用的 esbuild 压缩器；重新赋值 import.meta.hot.data。
流程反模式：vite preview 不是生产服务器，仅用于构建产物的冒烟测试；不要期望 vite build 做类型检查；默认引入 @vitejs/plugin-legacy 会增大包体积；手写大量 resolve.alias 重复 tsconfig.json 路径；依赖变更后残留 node_modules/.vite 缓存会导致异常错误。

技能介绍

用途