Vite项目长期可维护性关键在于配置拆分、职责分离与结构规范：按proxy/alias/build等职责拆配置文件，用函数式defineConfig动态适配serve/build，禁用require改用import，隔离服务端逻辑，优化构建内存，按能力域分层src目录并明确模块契约。
Vite 构建本身轻快高效，但项目规模上去后，很容易因配置或组织方式不当，掉进“看似能跑、实则脆弱”的反模式陷阱。真正影响长期可维护性的，往往不是语法错误，而是那些没被及时识别的工程惯性——比如把所有逻辑塞进一个 config 文件、用 require 混搭 ESM、或者让构建内存随模块数线性增长。
别把 vite.config.ts 写成“全能胶水”
常见做法是把 proxy、alias、plugins、build 配置全堆在一个文件里，加注释都救不了可读性。久而久之，改个代理路径要翻 200 行，加个环境变量怕牵连压缩配置。
- 按职责拆：单独抽
proxy.ts管开发代理，alias.ts管路径映射，build.ts管输出规则 - 用函数式配置动态合并：
defineConfig(({ command, mode }) => { ... })，让 serve 和 build 各走各的逻辑分支 - 避免在 config 里写业务逻辑（比如读取本地 JSON 当配置），这类操作应移入构建前脚本或运行时环境变量
别在客户端代码里用 require
require('./utils') 在 Vite 中直接报错 “require is not defined”，这不是 bug，是设计使然——Vite 开发服务器基于原生 ES 模块，不模拟 Node.js 的 CommonJS 运行时。
- 统一改用
import语法，包括第三方包（如 lodash）也要用import { debounce } from 'lodash' - 若必须兼容旧代码，可通过插件
vite-plugin-commonjs转译，但仅限过渡期，不建议长期依赖 - 服务端逻辑（如 SSR 工具函数）务必和客户端入口物理隔离，避免误引入
别放任构建内存无节制增长
Rollup 生产构建会把整个依赖图加载进内存做 AST 分析，模块一多、插件一杂，就容易触发 FATAL ERROR: Reached heap limit。
- 先确认是否真缺内存：运行
node -e "console.log(require('v8').getHeapStatistics().heap_size_limit / 1024 / 1024 + ' MB')"查当前上限 - 优先优化而非扩容：禁用非必要插件（如冗余的 sourcemap 插件）、拆分大 bundle（用
build.rollupOptions.output.manualChunks）、清理未使用导出（启用treeShaking: true） - 仅当确需扩容时，才在构建命令中加参数：
node --max-old-space-size=6144 node_modules/vite/bin/vite.js build
别让项目结构滑向“大泥球”
没有边界感的 src 目录，比如 /utils/api.js 里混着请求封装、拦截器、token 刷新逻辑，/components 里塞着 UI 组件和数据容器组件，时间一长，改一个接口要动五个文件。
- 按能力域分层：明确
features/（业务功能）、shared/（跨功能复用）、entities/（领域模型）、services/（网络/存储等副作用） - 组件只负责渲染，数据获取交给自定义 Hook 或 services 层，禁止在 JSX 中调
fetch - 每个模块导出清晰契约：只暴露必要的函数/类型，内部实现细节不泄露
