05-工具配置文档.md 11 KB

工具配置文档

一、命令

命令 作用
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 取值:

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,部署后不可改。

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,这一句不要改:

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,兼容老浏览器
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、不自己建实例。

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,拿到的就是业务数据:

const list = await pageApi(query)   // 直接是 { list, total }

api 文件写法

按后端模块建文件,放 src/api/:

// 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`

页面里:

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

文件上传

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,不要自己写色值:

<span style="color: var(--s-color-success)">启用</span>

常用 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 缓存再试