# 工具配置文档 ## 一、命令 | 命令 | 作用 | |---|---| | `npm run dev`(或 `yarn dev`) | 起开发服务,端口见 `vite.config.js` | | `npm run start` | 先跑 `refresh-mode.ps1` 重新拉基座依赖,再起服务。基座发了新版用这个 | | `npm run build` | 先跑 `refresh-build.ps1` 拉依赖,再 `vite build` 出 `dist` | | `npm run preview` | 本地预览 `dist` | | `npm run lint` | ESLint 自动修 | | `npm run format` | Prettier 格式化 `src/` | 包管理统一用 `yarn@1.22.22`(`package.json` 里 `packageManager` 已锁定)。 --- ## 二、环境变量 三个文件,后者覆盖前者:`.env`(公共)→ `.env.development` / `.env.production`(环境差异)。 | 变量 | 示例 | 说明 | |---|---|---| | `NODE_ENV` | `development` | 环境标识 | | `VITE_APP_API_BASE_URL` | `http://192.168.200.7:6801/` | 后端服务地址。开发填真实地址,生产留空走 nginx 同源 | | `VITE_APP_API_PATH` | `/apig` | 接口统一前缀,与 `BASE_URL` 拼成请求 baseURL | | `VITE_APP_API_FILE_URL` | 空 | 文件服务地址(头像、附件预览) | | `VITE_APP_SOCKET_URL` | 同 BASE_URL | WebSocket 地址 | | `VITE_APP_PREVIEW_ONLINE` | `/filePreview/onlinePreview?url=` | 附件在线预览前缀 | | `VITE_APP_BASE_URL` | `/` | 部署子路径,如 `/portal/` | | `VITE_APP_CLIENT_ID` | `mm0001` | 认证中心 clientId,每个项目不同 | | `VITE_APP_SYS_SERVER_NAME` | `portal` | **业务网关名**,接口 url 前缀就用它 | | `VITE_APP_PORTAL_SERVER_NAME` | `portal` | 平台网关(组织、用户、字典、文件接口都在这个网关) | | `VITE_APP_MESSAGE_SERVER_NAME` | `message` | 消息网关 | | `VITE_APP_FLOW_SERVER_NAME` | `flow` | 工作流网关 | | `VITE_APP_PROJECT_NAME` | `平台系统` | 系统名 | | `VITE_APP_TITLE` | `统一认证中心` | 浏览器页签标题 | | `VITE_APP_VERSION` | `v1.0` | 版本号,页脚展示 | | `VITE_APP_LOGIN_PHONE` | `false` | 登录页显示手机号登录 | | `VITE_APP_LOGIN_QRCODE` | `false` | 登录页显示扫码登录 | | `VITE_APP_LOGIN_PATH_THEME` | `4` | 登录页版式(1 左图右表单 / 2 左表单右背景 / 3 居中表单 / 4 模版默认版式) | | `VITE_APP_LOGIN_CASE_NAME` | `辽ICP备...` | 登录页备案号 | | `VITE_APP_BASE_CASE_NAME` | 同上 | 系统页脚备案号 | | `VITE_APP_FOOTER_VISIBLE` | `false` | 是否显示页脚 | | `VITE_APP_MESSAGE_VISIBLE` | `true` | 右上角消息铃铛 | | `VITE_APP_LANG_ENABLE` | `false` | 是否启用国际化(关掉时 `$l` 直接返回中文) | | `VITE_APP_LANG` | `zh` | 默认语言 `zh` / `en` | | `VITE_APP_MENU_THEME` | `dark` | 菜单主题 `dark` / `light` | | `VITE_APP_MENU_BAR` | `left` | 菜单位置 `left` / `top` | | `VITE_APP_THEME_VALUE` | `blue` | 主题色名,取值由基座主题表提供 | | `VITE_APP_PC_HOST` | 空 | PC 访问地址,富文本图片地址替换用 | | `VITE_APP_WEB_SITE` | 空 | 官网地址 | | `VITE_APP_JSS_LICENSE` | 空 | JSSDK license | 改完环境变量必须重启 `vite`(`.env` 不进热更新)。 --- ## 三、三层配置 | 层 | 文件 | 什么时候改 | 改完怎么生效 | |---|---|---|---| | 基座默认 | 无 | 不改 | — | | 项目配置 | `src/config/web-config.js`、`src/config/app-config.js` | 开发期 | 重启服务 | | 部署配置 | 构建产物根目录的 `config.json` | 上线后 | 改完刷新浏览器即生效 | 优先级:**基座默认 < 项目配置 < 部署 `config.json`**。 部署后要调网关地址、标题这类值,改部署目录里的 `config.json`;改 `web-config.js` 只对下一次构建生效。同名键以 `config.json` 为准。 ### web-config.js 运行时可改的纯值配置。字段与 `.env` 一一对应,从 `import.meta.env` 取值: ```js export default { VITE_APP_PROJECT_NAME: import.meta.env?.VITE_APP_PROJECT_NAME, VITE_APP_TITLE: import.meta.env?.VITE_APP_TITLE, VITE_APP_API_BASE_URL: import.meta.env?.VITE_APP_API_BASE_URL, VITE_APP_API_PATH: import.meta.env?.VITE_APP_API_PATH, VITE_APP_SYS_SERVER_NAME: import.meta.env?.VITE_APP_SYS_SERVER_NAME, // 业务自定义的默认首页 VITE_APP_DEFAULT_PATH: '/workplace/index', // 仅开发时显示基座 demo 页(业务项目必须 false) VITE_APP_IS_BASE: false } ``` 这些值在 `vite build` 时被写进 `dist/config.json`,部署后可以直接改这个 json 调整网关地址、标题、默认首页。 ### app-config.js 构建期配置,**含函数和组件,不进 config.json**,部署后不可改。 ```js export default { // 覆盖基座自带的登录页 / 首页(不配则用基座的) components: { login: () => import('@/views/default/login/index.vue'), home: () => import('@/views/default/home/index.vue') }, // 不依赖后端菜单的固定页面 staticRoutes: [ { path: '/developmentProcess', name: 'developmentProcess', layout: false, component: () => import('@/views/static/page/DevelopmentProcess.vue'), meta: { title: '开发流程', public: true, hidden: true } } ], // 业务语言包:views/<模块>/i18n.js 与 locales/**/i18n.js 自动收集 locales: import.meta.glob(['@/views/**/i18n.js', '@/locales/**/i18n.js'], { eager: true }) } ``` `main.js` 把 `web-config` 和 `app-config` 合并后交给基座的 `$registerGlobalConfig`,这一句不要改: ```js await app.config.globalProperties.$registerGlobalConfig({ ...config, ...appConfig }, pages) ``` --- ## 四、vite.config.js 大部分保持模版原样,只动这几处: | 位置 | 说明 | |---|---| | `base` | 取自 `VITE_APP_BASE_URL`,子路径部署时改 env | | `server.port` | 开发端口,**每个项目不一样** | | `server.strictPort: true` | 端口被占直接启动失败而不是自动换端口,改了会让联调地址对不上 | | `server.proxy['/apig'].target` | 取 `VITE_APP_API_BASE_URL`,开发跨域靠它 | | `resolve.alias['@']` | 指向 `src`,不要动 | | `resolve.dedupe` | `vue` / `vue-router` / `pinia` / `vue-i18n` / `ant-design-vue` 必须保留 | | `optimizeDeps.exclude` | `sapit-ui-plus`、`sapit-ui-components` 必须保留 | | `build.outDir` | `dist` | | `build.target` | `es2015`,兼容老浏览器 | ```js server: { port: 6599, // 每个项目改这一个 strictPort: true, host: '0.0.0.0', proxy: { '/apig': { target: getViteEnv(res.mode, 'VITE_APP_API_BASE_URL'), changeOrigin: true } } } ``` `dedupe` 和 `optimizeDeps.exclude` 是保证基座和业务共用同一份 vue / router / pinia 实例的开关,删了会出现路由跳不动、store 读写不生效这类怪现象。 构建产物除静态资源外还会生成 `config.json`(由 `web-config.js` + env 合成,已格式化成多行便于手改)。 --- ## 五、请求层 ### 用法 业务统一用 `window.$utils.http`,不自己装 axios、不自己建实例。 ```js window.$utils.http({ url: `/${window.$utils.env.VITE_APP_SYS_SERVER_NAME}/position/page`, data: { pageNum: 1, pageSize: 20 } }) ``` ### 行为 | 项 | 说明 | |---|---| | baseURL | `VITE_APP_API_BASE_URL`(去尾斜杠)+ `VITE_APP_API_PATH`,开发环境下即 `http://后端:端口/apig` | | 默认 method | **`post`**,需要 GET 时显式写 `method: 'get'` | | 请求头 | 自动带 `user-token`、`client-id`、`user-router`(当前路由),不要手动加 | | 超时 | 120 秒 | | 返回值 | 后端 `{ status: 1, data }` → 直接拿到 **`data`**,已经解包 | | `status: 0` | 弹错误通知并 `reject`,业务只需 `.catch()` | | `status: -1` | 登录超时,自动跳登录页并 `reject` | | 文件响应 | 响应是 zip/pdf/图片时自动触发浏览器下载 | 所以业务代码里**不要再判断 `res.status` / `res.code`**,拿到的就是业务数据: ```js const list = await pageApi(query) // 直接是 { list, total } ``` ### api 文件写法 按后端模块建文件,放 `src/api/`: ```js // src/api/position.js const gateway = () => window.$utils.env.VITE_APP_SYS_SERVER_NAME // 分页列表:query 是页面查询条件,parameter 是表格传的分页排序对象 export function page(query = {}, parameter = {}) { return window.$utils.http({ url: `${gateway()}/position/page`, data: { ...query, pageNum: parameter.pageNo, pageSize: parameter.pageSize, sortField: parameter.sortField, sortOrder: parameter.sortOrder } }) } export function getById(id) { return window.$utils.http({ url: `${gateway()}/position/getById?id=${id}`, method: 'get' }) } export function save(data) { return window.$utils.http({ url: `${gateway()}/position/save`, data }) } export function deleteById(id) { return window.$utils.http({ url: `${gateway()}/position/deleteById?id=${id}`, method: 'get' }) } // 批量删除:接收选中行 key 数组(列表工具栏 remove 按钮直接调它) export function deleteByIds(ids = []) { return window.$utils.http({ url: `${gateway()}/position/deleteByIds`, data: ids }) } // 导出:响应是文件流,浏览器会自动下载 export function exportExcel(query = {}) { return window.$utils.http({ url: `${gateway()}/position/exportExcel`, data: query }) } // 上传地址(给 s-file-upload / 导入弹窗用,需要完整前缀) export const IMPORT_UPLOAD_URL = `${window.$utils.env.VITE_APP_API_BASE_URL || ''}${window.$utils.env.VITE_APP_API_PATH || ''}/${window.$utils.env.VITE_APP_SYS_SERVER_NAME}/position/import` ``` 页面里: ```js import { page as pageApi, save, getById, deleteById } from '@/api/position' ``` ### 网关选择 | 接口类型 | 用哪个网关变量 | |---|---| | 业务自己的接口 | `VITE_APP_SYS_SERVER_NAME` | | 组织、用户、角色、字典、文件、参数 | `VITE_APP_PORTAL_SERVER_NAME` | | 消息、待办 | `VITE_APP_MESSAGE_SERVER_NAME` | | 工作流 | `VITE_APP_FLOW_SERVER_NAME` | ### 文件上传 ```js const formData = new FormData() formData.append('file', file) window.$utils.http({ url: `/${window.$utils.env.VITE_APP_PORTAL_SERVER_NAME}/file/upload?businessTableName=xxx&uid=${uid}`, data: formData, headers: { 'Content-Type': 'multipart/form-data' } }) ``` 表单里的上传直接用 `s-file-upload`,它会处理好这些。 --- ## 六、主题与布局 | 需求 | 改哪里 | |---|---| | 主题色 | `.env` 的 `VITE_APP_THEME_VALUE`(值由基座主题表定义,默认 `blue`) | | 菜单深/浅色 | `VITE_APP_MENU_THEME` = `dark` / `light` | | 菜单在左/在顶 | `VITE_APP_MENU_BAR` = `left` / `top` | | 登录页版式 | `VITE_APP_LOGIN_PATH_THEME` | | 默认首页 | `web-config.js` 的 `VITE_APP_DEFAULT_PATH` | | 页脚 / 备案号 | `VITE_APP_FOOTER_VISIBLE`、`VITE_APP_BASE_CASE_NAME` | | 全局样式变量 | `src/assets/main.less`(CSS 变量以 `--s-` 开头,如 `var(--s-color-success)`) | 代码里取主题对象用 `window.$theme`,不要自己写色值: ```vue 启用 ``` 常用 CSS 变量:`--s-bg-color-container`、`--s-bg-color`、`--s-text-color-regular`、`--s-border-color-split`、`--s-color-success`、`--s-color-error`、`--s-menu-bg`。 --- ## 七、基座有新版时 1. 改 `package.json` 里 `sapit-ui-plus` 的版本或分支(当前是 `git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git`) 2. `npm run start`(会先执行 `refresh-mode.ps1` 重新拉取依赖) 3. 起不来先删 `node_modules/.vite` 缓存再试