环境变量
Art Design Pro X 使用 Vite 的环境变量机制管理开发端口、部署路径、接口地址、菜单来源、存储隔离和版本更新策略。环境变量属于工程配置，不应该承担业务数据或密钥管理职责。
环境文件
项目根目录包含三类环境文件：
| 文件 | 加载时机 | 适合配置 |
|---|---|---|
.env | 所有模式 | 版本、端口、基础路径、菜单来源、存储命名空间 |
.env.development | pnpm dev | 开发代理、开发日志开关 |
.env.production | pnpm build | 生产 API、部署路径、控制台移除 |
同名变量以当前模式文件为准。例如 .env.development 中的 VITE_API_URL 会覆盖 .env 中的值。
修改后需要重启
Vite 在开发服务启动时读取环境文件。修改 .env* 后，应停止并重新执行 pnpm dev。
核心变量
应用与部署
VITE_VERSION = 1.0.0
VITE_PORT = 3000
VITE_BASE_URL = /VITE_VERSION：应用版本，参与版本化存储和发布识别。VITE_PORT：本地开发服务器端口。VITE_BASE_URL：应用部署基础路径。部署到/admin/时应设置为/admin/，并同步配置 Web 服务器回退规则。
接口与代理
VITE_API_URL = /
VITE_WITH_CREDENTIALS = false开发环境推荐继续使用相对地址，并通过代理连接后端：
# .env.development
VITE_API_URL = /
VITE_API_PROXY_URL = http://localhost:13000浏览器请求 /api/... 和 /uploads/...，Vite 将请求转发至 VITE_API_PROXY_URL。生产环境建议由 Nginx 或网关提供同源转发，减少跨域配置和 Cookie 策略带来的复杂度。
只有明确采用跨域 Cookie 会话时才启用：
VITE_WITH_CREDENTIALS = true项目默认使用 Bearer Token，因此通常保持 false。
菜单来源
VITE_MENU_SOURCE = local可选值：
| 值 | 行为 | 适用场景 |
|---|---|---|
local | 使用 src/router/modules，按当前用户角色过滤 | 前端维护菜单、快速交付 |
remote | 请求 /api/v1/user/menus 并注册动态路由 | 后端统一维护菜单和租户权限 |
切换到 remote 前，应先完成菜单接口并通过路由与权限中描述的结构校验。
本地数据延迟
VITE_MOCK_DELAY = 60该值控制 src/mock 的可选延迟，单位为毫秒。设为 0 可以关闭。它只用于模拟异步页面体验，不代表真实网络性能，也不应出现在生产性能指标中。
存储命名空间
VITE_STORAGE_NAMESPACE = sys项目持久化键采用以下格式：
{namespace}-v{version}-{storeId}客户项目应将默认值改成独立、稳定的命名空间，例如：
VITE_STORAGE_NAMESPACE = acme-admin同一域名下部署多个系统时，独立命名空间可以避免用户偏好、Token 和表格配置互相覆盖。上线后不要频繁修改，否则浏览器会把它识别成一套新的本地数据。
路由调试与锁屏
VITE_OPEN_ROUTE_INFO = false
VITE_LOCK_ENCRYPT_KEY = replace-with-project-specific-valueVITE_OPEN_ROUTE_INFO：控制路由调试信息，生产环境建议关闭。VITE_LOCK_ENCRYPT_KEY：用于前端锁屏数据处理，应替换为项目独立值。
锁屏密钥位于浏览器构建产物中，只能降低明文暴露，不是服务端安全密钥，也不能替代登录鉴权。
版本更新配置
VITE_BUILD_ID =
VITE_VERSION_UPDATE_ENABLED = false
VITE_VERSION_FORCE_UPDATE = false
VITE_VERSION_UPDATE_MESSAGE =
VITE_VERSION_CHECK_INTERVAL = 300000
VITE_VERSION_SNOOZE_DURATION = 1800000推荐在 CI 中为 VITE_BUILD_ID 注入提交 SHA 或流水线编号。未显式提供时，构建配置会使用版本号与构建时间生成标识。
启用版本提示时，应区分普通更新和强制更新：
- 普通更新允许用户稍后处理，适合非阻断式界面改进。
- 强制更新用于协议变化、关键安全修复或旧资源无法继续工作的情况。
- 检查间隔不宜过短，避免无意义请求和频繁弹窗。
TypeScript 类型声明
环境变量类型位于 src/env.d.ts。新增变量后应同步声明，避免在业务代码中到处进行字符串断言：
interface ImportMetaEnv {
readonly VITE_API_URL?: string
readonly VITE_MENU_SOURCE?: 'local' | 'remote'
readonly VITE_STORAGE_NAMESPACE?: string
}读取时统一使用：
const apiUrl = import.meta.env.VITE_API_URL || '/'布尔值和数字在 import.meta.env 中仍然是字符串，需要在配置层完成解析和默认值处理。
安全边界
所有以 VITE_ 开头的变量都会进入浏览器构建产物，用户可以在 JavaScript、Source Map 或网络请求中看到它们。因此以下内容不能写入环境文件：
- 数据库密码、对象存储 Secret
- JWT 签名密钥
- 第三方服务私钥
- 服务端管理令牌
- 任何依赖“用户看不到”才能安全的信息
真正的密钥必须保存在后端或部署平台的服务端环境中。
推荐配置流程
- 修改
VITE_STORAGE_NAMESPACE，确保客户项目存储隔离。 - 确认
VITE_BASE_URL与实际部署路径一致。 - 开发环境配置
VITE_API_PROXY_URL。 - 按菜单管理方式选择
local或remote。 - 在 CI 中注入
VITE_BUILD_ID。 - 执行
pnpm build，检查构建和路由基础路径。