配置说明

环境文件

Vite 会按模式合并 .env、.env.development 与 .env.production。只有以 VITE_ 开头的变量会暴露给浏览器代码，因此不要在这些文件中保存密码、私钥或任何服务端密钥。

变量	作用	示例
VITE_API_URL	生产环境主 API 基础地址	https://api.example.com/
VITE_BASE_URL	应用部署基础路径，路由和构建共用	/admin/
VITE_TOKEN_KEY	localStorage 中的 Token 键名	admin_token
VITE_NEW_TOKEN_KEY	响应头中的续签 Token 键名	New-Access-Token
VITE_WITH_CREDENTIALS	跨域请求是否携带 Cookie	true
VITE_API_URL_LOCAL	自有独立服务地址，默认携带 Token	https://file.example.com/
VITE_API_URL_EXTERNAL	第三方服务地址，默认不携带 Token	https://open.example.com/

推荐生产配置：

VITE_API_URL=https://api.example.com/
VITE_BASE_URL=/admin/
VITE_TOKEN_KEY=admin_token
VITE_NEW_TOKEN_KEY=New-Access-Token
VITE_WITH_CREDENTIALS=false

公开仓库注意

提交前执行 git grep -n -I -E "(password|secret|token|api[_-]?key|private[_-]?key)"，人工核查结果。即便变量以 VITE_ 开头且位于 .env，构建后也能被所有访客读取。

Vite 配置

vite.config.ts 负责：

• 使用 VITE_BASE_URL 设置构建基础路径。
• 注册 Vue 与自动导入插件。
• 为浏览器补齐文件解析依赖需要的 Node polyfill。
• 配置 @ 指向 src。
• 预构建常用依赖以改善冷启动。
• 将图标、ECharts、编辑器、Naive UI 等大依赖拆成独立 chunk。

系统与主题配置

系统标题、Logo、备案信息等从 api/system/query-info.json（真实项目应为系统信息接口）加载。主题和布局默认值位于 src/stores/settings.ts，用户修改后保存到 localStorage，并通过 storage 事件同步到其他标签页。

如果新增设置字段，应同时修改默认 state。项目的设置持久化带 schema 迁移，升级版本时会保留仍有效的旧偏好、补齐新字段并移除废弃字段。

路径书写约定

• API 基础地址建议以 / 结尾。
• 动态菜单的 component 是相对 src/views/ 的路径，例如 auth/user/index.vue。
• VITE_BASE_URL=/admin/ 时，Vue Router 和 Vite 必须使用相同路径。
• 外部链接与 iframe 地址必须由可信后端控制，并建议设置 CSP 和允许域名列表。