状态与配置流

本文说明 art-design-pro-x-ui 中状态和配置的来源。它适合在排查“配置已修改但页面未生效”“刷新后状态丢失”“菜单或语言不一致”等问题时阅读。

状态模块

前端状态集中在 src/store/modules：

模块	职责
user.ts	登录状态、Access Token、用户信息、语言设置
menu.ts	菜单数据、菜单选中状态、路由菜单映射
site-settings.ts	后端公开站点配置与管理端站点配置
setting.ts	布局、主题、顶部栏、设置面板相关状态
notification.ts	通知相关状态
table.ts	表格偏好与列配置状态
worktab.ts	工作标签页状态

配置来源

前端配置主要来自三类来源：

来源	示例	适用内容
环境变量	.env.development、.env.production	端口、基础路径、API 地址、代理目标
静态配置	src/config/index.ts、src/config/setting.ts、src/config/modules/*	默认主题、布局、顶部栏、快捷入口、全局搜索
后端公开配置	site-settings store	站点名称、欢迎文案、默认语言、注册开关等

站点配置加载顺序

应用启动后会加载公开站点配置。仅在用户未保存且未在本次访问中手动选择语言时，应用站点配置中的默认语言；不覆盖已有语言偏好，也不以登录状态作为唯一条件。

flowchart TD
  A["main.ts 启动应用"] --> B["加载 Pinia / Router / i18n"]
  B --> C["loadPublicSiteSettings()"]
  C --> D["写入 site-settings store"]
  D --> E["无语言偏好时应用站点默认语言"]
  E --> F["页面读取站点展示配置"]

因此，品牌文案、默认语言等展示问题需要同时检查前端默认配置和后端公开站点配置。

环境变量与接口地址

开发环境常见配置：

VITE_API_URL = /
VITE_API_PROXY_URL = http://localhost:13001
# Nest.js 使用 http://localhost:13000，只启用一个代理目标

生产环境常见配置：

VITE_BASE_URL = /
VITE_API_URL = /

以上生产示例适用于前端与 API 共用站点、由网关转发 /api 的部署方式；独立 API 域名部署时，使用客户实际 API Origin，例如 https://api.example.com。不要把任一官方演示域名作为客户部署的默认后端。

理解方式：

• VITE_BASE_URL 影响静态资源和路由基础路径。
• VITE_API_URL 影响请求基础地址。
• VITE_API_PROXY_URL 只影响开发服务器代理目标。

排查建议

现象	优先检查
页面文案没有变化	后端公开站点配置、浏览器缓存、前端默认配置
默认语言不符合预期	本地持久化语言、站点配置 defaultLanguage、语言包 key
开发环境接口不通	VITE_API_URL、VITE_API_PROXY_URL、后端端口
生产环境资源 404	VITE_BASE_URL 与部署路径是否一致
刷新后登录状态异常	Refresh Token Cookie、代理、withCredentials

维护建议

• 环境差异放在 .env* 中，不要写进业务页面。
• 项目默认展示值放在 src/config 中，运行时可变展示值优先走站点配置。
• 多处页面共享的状态应进入 store，避免页面间通过临时变量同步。
• 可复用的业务逻辑优先沉淀为 hooks 或 utils，再由页面组合使用。