xuanzhi-service/web/.ai-specs/sys-specs/env-build-spec.md

env-build-spec

适用范围

• 涉及 .env.*、vite.config.js、package.json scripts、构建参数和部署相关配置时必读。

当前构建链路

• 开发命令以 package.json 中的 dev / serve 为入口。
• 构建命令以 package.json 中的 build 为入口。
• Vite 主配置文件为 vite.config.js。
• 运行时接口基地址由 import.meta.env.VITE_BASE_API 提供，消费点在 src/utils/request.js。

强制规则

• 新增前端环境变量时，变量名必须使用 VITE_ 前缀。
• 变更环境变量时，必须同步检查 .env.development、.env.production 和实际消费点。
• 变更构建配置时，必须同步检查 vite.config.js、package.json scripts、Dockerfile 和部署路径假设。
• 禁止把业务常量长期堆进 .env.*；只有部署环境相关变量才放环境文件。

联动检查

• 改 VITE_BASE_API 或其消费方式：同步检查 src/utils/request.js 和所有上传/下载接口。
• 改 Vite alias、静态资源策略或 publicPath：同步检查路由、静态资源引用和部署环境。
• 改 scripts：同步检查 README、Docker 构建命令和团队既有运行方式。

常见错误

• 只改一个环境文件，导致开发和生产行为不一致。
• 在页面或 API 文件里硬编码后端域名，绕过 VITE_BASE_API。
• 修改构建配置后没有验证登录页、主布局页和插件页是否还能正确加载资源。