vite.config.ts核心配置需聚焦问题场景：server.port/host解决端口冲突与局域网访问；resolve.alias须同步tsconfig.paths防TS报错；build.manualChunks拆分node_modules提升缓存复用；define注入编译常量比环境变量更安全；loadEnv配合mode实现多环境自动切换。
制定 Vite 配置项详解与调优策略指南，核心是围绕 vite.config.ts（或 .js）中真正影响开发体验、构建性能和产物质量的关键配置展开，避免堆砌文档式罗列，聚焦“为什么配”“怎么配更稳”“什么场景要调”。以下为实用导向的结构化指南框架：
一、基础配置：从 devServer 到 build 输出路径
这是项目启动和打包的起点，多数新手卡点在此。
- server.port / host / open：本地开发端口冲突时优先改 port；需局域网访问务必设 host: '0.0.0.0'；open: true 可省去手动开浏览器步骤
- build.outDir / assetsDir：默认 dist 不适合多环境部署，建议按环境变量区分，如 outDir: `dist-${process.env.NODE_ENV}`
- build.rollupOptions.output.manualChunks：对 node_modules 中大依赖（如 antd、echarts）单独拆包，减少主包体积，提升缓存复用率
二、模块解析与别名优化
直接影响 import 书写效率和 HMR 稳定性。
- resolve.alias：推荐用绝对路径别名（如 @/components），但注意在 tsconfig.json 的 compilerOptions.paths 中同步声明，否则 TS 类型检查会报错
- resolve.dedupe：当多个依赖引入同一份包（如 react、react-dom）但版本不一致时，强制统一实例，避免运行时 Hooks 错误
- 慎用 resolve.extensions：默认 ['.mjs', '.js', '.ts', '.jsx', '.tsx', '.json'] 已足够，盲目追加 '.vue' 或 '.svelte' 可能拖慢解析
三、插件协同与构建性能调优
插件不是越多越好，关键看是否解决真实瓶颈。
- define：用于注入编译期常量（如 __APP_VERSION__ = `"${pkg.version}"`），比环境变量更安全、无 runtime 开销
- optimizeDeps.include / exclude：遇到 ESM 兼容问题（如某 UI 库未导出 .mjs）时，将其加入 include 强制预构建；大型工具库（如 lodash-es）可 exclude 后按需导入，避免全量打入
- build.sourcemap：开发环境建议 'inline'，生产环境若需调试则用 'hidden'（不上传 map 文件但保留 sourceMappingURL），禁用则设 false
四、环境适配与 CI/CD 友好实践
让配置随环境自然切换，而非靠手动改文件。
- 使用 mode + loadEnv 加载 .env.[mode] 文件，例如 .env.production 自动注入 VUE_APP_API_BASE
- build.lib 模式下必须显式配置 entry 和 name，且 rollupOptions.external 要排除 peerDependencies（如 vue、react），否则打包会把它们打进 bundle
- CI 构建时建议加 build.minify: 'terser' 并配 terserOptions.drop_console: true，避免依赖 esbuild 默认压缩丢失某些 tree-shaking 机会
不复杂但容易忽略。真正有效的配置指南，是把每个选项放在具体问题里讲清楚——比如“为什么 alias 配了却 TS 报错”，而不是只写“alias 是配置路径别名”。
