| 命令 | 作用 |
|---|---|
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 为准。
运行时可改的纯值配置。字段与 .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 调整网关地址、标题、默认首页。
构建期配置,含函数和组件,不进 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)
大部分保持模版原样,只动这几处:
| 位置 | 说明 |
|---|---|
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 }
按后端模块建文件,放 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。
package.json 里 sapit-ui-plus 的版本或分支(当前是 git+http://192.168.200.4:6110/sapit/sapit-ui-plus.git)npm run start(会先执行 refresh-mode.ps1 重新拉取依赖)node_modules/.vite 缓存再试