Vite

核心用法

Vite Patterns 是一套围绕 Vite 构建工具的配置最佳实践集合，覆盖从开发环境到生产部署的全链路优化。核心用法分为五大维度：

1. 环境变量管理：VITE_ 前缀变量通过 import.meta.env 注入客户端，区别于 Node 的 process.env；.env.local 用于本地敏感配置且默认 gitignore
2. 依赖预打包：首次启动时自动预编译依赖，通过 optimizeDeps.include/exclude 精细控制缓存策略，删除 node_modules/.vite 可强制重建
3. 路径别名配置：需在 vite.config.ts 和 tsconfig.json 双重配置，推荐使用 path.resolve(__dirname, './src') 确保路径稳定性
4. 开发服务器代理：支持 HTTP/WebSocket 代理，配置 changeOrigin: true 解决跨域，ws: true 显式转发 WebSocket
5. 静态资源处理：public/ 目录原样复制，src/assets/ 经过哈希处理，动态路径使用 new URL('./img.png', import.meta.url)

显著优点

• 极速开发体验：基于原生 ESM 的 HMR 毫秒级更新，预打包机制避免重复编译
• 开箱即用与深度可控并存：默认配置覆盖 80% 场景，同时提供 rollupOptions、manualChunks 等底层配置入口
• 双模式支持：应用模式与库模式（build.lib）共用一套配置体系，降低多场景学习成本
• SSR 友好：ssr.external/noExternal 精确控制 Node 端依赖打包行为，解决同构渲染常见陷阱

潜在缺点与局限性

• CommonJS 兼容包袱：纯 ESM 设计导致部分遗留包需手动配置 optimizeDeps，命名导出解构需采用 import pkg from 'pkg' 迂回写法
• 代理仅限开发：生产环境必须配置真实 CORS 或反向代理，易与开发环境产生行为差异
• HMR 边界复杂：循环依赖、CSS 在 JS 中导入等场景可能触发全量刷新，需理解热更新边界
• 类型生成缺失：库模式下需单独运行 tsc 生成 .d.ts，Vite 本身不处理类型输出

适合人群

• 已使用或计划迁移至 Vite 的前端开发团队
• 需要构建 npm 库（双格式 ESM/CJS）的库作者
• 对构建产物体积、代码分割策略有精细化要求的工程师
• 处理 SSR/SSG 场景的同构应用开发者

常规风险

• 环境变量泄露：误将敏感变量命名为 VITE_ 前缀会导致打包进客户端代码
• 缓存失效陷阱：修改依赖版本后未清除 node_modules/.vite 可能引入陈旧预打包产物
• 路径别名不一致：仅配置 Vite 而忽略 TypeScript 配置会导致 IDE 报错与运行时行为分离
• 生产代理失效：开发期依赖代理绕过 CORS，上线前未配置实际跨域策略导致接口失败

核心用法

本 Skill 是一份面向 Vite 开发者的配置指导文档，并非可执行工具，而是通过结构化的知识模块帮助开发者正确配置和优化 Vite 项目。内容覆盖 11 个核心场景：环境变量管理、CommonJS 兼容、依赖预构建、路径别名配置、开发服务器代理、静态资源处理、构建优化、Library 模式、HMR 热更新问题排查以及 SSR 配置。

每个模块均采用"问题-原理-解决方案"的三段式结构。例如环境变量章节明确指出仅 VITE_ 前缀变量会暴露给客户端，并强制使用 import.meta.env 而非 Node 的 process.env；路径别名章节则强调必须在 vite.config.ts 和 tsconfig.json 中同步配置，避免因解析策略差异导致类型检查失败。

显著优点

权威性：内容源自 Vite 官方文档与社区实战经验的深度整合，涉及底层机制如 optimizeDeps 预构建缓存策略、rollupOptions 代码分割配置等进阶话题。

实用性：提供可直接复用的配置代码片段，如代理服务器的 rewrite 路径处理、Library 模式的 external 依赖排除等，显著降低配置试错成本。

风险前置：主动披露常见陷阱——如 changeOrigin: true 对 Host 头的影响、HMR 中循环依赖导致的热更新失效、CSS 在 SSR 中的导入限制等，帮助开发者提前规避生产事故。

潜在缺点与局限性

时效性约束：Vite 版本迭代较快，部分配置项（如 optimizeDeps 的行为）可能在后续版本中调整，建议结合官方文档交叉验证。

场景覆盖边界：聚焦于通用 Web 应用与 Library 开发，对微前端、Electron 等复杂集成场景涉及较少，需开发者自行扩展。

无自动化能力：作为纯文档型 Skill，不提供代码生成或自动修复功能，配置迁移仍需人工执行。

适合的目标群体

• 中高级前端开发者：已具备 Vite 基础使用经验，需解决特定配置问题或优化构建性能
• 技术负责人/架构师：评估 Vite 工程化方案，制定团队规范
• 开源 Library 维护者：需配置 Library 模式打包 ESM/CJS 双格式输出

使用风险

本 Skill 本身无代码执行风险，但应用其建议时需注意：

1. 环境变量泄露风险：若误将敏感变量添加 VITE_ 前缀，将导致密钥暴露至客户端代码
2. 代理配置误用：生产环境直接复用 server.proxy 配置会导致 API 调用失败，需配置实际 CORS 或反向代理
3. 构建目标兼容性：build.target 设为现代浏览器可减小包体积，但可能破坏旧版浏览器兼容性
4. 依赖预构建缓存：node_modules/.vite 缓存损坏可能导致开发服务器异常行为，需掌握强制重建时机