项目配置项
用于修改项目的配色、布局、缓存、多语言、组件默认配置以适配自身项目需求
环境变量配置
项目的环境变量配置位于 项目根目录 .env、.env.development、.env.production
具体可以参考Vite 文档
.env # 在所有的环境中被载入
.env.local # 在所有的环境中被载入,但会被 git 忽略
.env.[mode] # 只在指定的模式中被载入
.env.[mode].local # 只在指定的模式中被载入,但会被 git 忽略
温馨提醒
- 只有以
VITE_
开头的变量会被嵌入到客户端侧的包中,你可以在应用的代码中这样访问它们:
console.log(import.meta.env.VITE_PROT);
- 以
VITE_GLOB_*
开头的的变量,在打包的时候,会被加入_app.config.js配置文件当中.
配置项说明
vue-vite-admin\build\utils.ts
npm dotenv
不用各處加入新的環境變數,要集中在 .env
檔中管理它
package.json
"devDependencies": {
"dotenv": "^10.0.0",
}
.env
所有环境适用
# 端口号
VITE_PORT=3100
# 网站标题
VITE_GLOB_APP_TITLE=vben admin
# 简称,用于配置文件名字 不要出现空格、数字开头等特殊字符
VITE_GLOB_APP_SHORT_NAME=vben_admin
.env.development
开发环境适用
# 是否开启mock数据,关闭时需要自行对接后台接口
VITE_USE_MOCK=true
# 资源公共路径,需要以 /开头和结尾
VITE_PUBLIC_PATH=/
# 是否删除Console.log
VITE_DROP_CONSOLE=false
# 本地开发代理,可以解决跨域及多地址代理
# 如果接口地址匹配到,则会转发到http://localhost:3000,防止本地出现跨域问题
# 可以有多个,注意多个不能换行,否则代理将会失效
VITE_PROXY=[["/api","http://localhost:3000"],["api1","http://localhost:3001"],["/upload","http://localhost:3001/upload"]]
# 接口地址
# 如果没有跨域问题,直接在这里配置即可
VITE_GLOB_API_URL=/api
# 文件上传接口 可选
VITE_GLOB_UPLOAD_URL=/upload
# 接口地址前缀,有些系统所有接口地址都有前缀,可以在这里统一加,方便切换
VITE_GLOB_API_URL_PREFIX=
注意
这里配置的VITE_PROXY
以及VITE_GLOB_API_URL
, /api 需要是唯一的,不要和接口有的名字冲突
如果你的接口是http://localhost:3000/api
之类的,请考虑将VITE_GLOB_API_URL=/xxxx
换成别的名字
.env.production
生产环境适用
# 是否开启mock
VITE_USE_MOCK=true
# 接口地址 可以由nginx做转发或者直接写实际地址
VITE_GLOB_API_URL=/api
# 文件上传地址 可以由nginx做转发或者直接写实际地址
VITE_GLOB_UPLOAD_URL=/upload
# 接口地址前缀,有些系统所有接口地址都有前缀,可以在这里统一加,方便切换
VITE_GLOB_API_URL_PREFIX=
# 是否删除Console.log
VITE_DROP_CONSOLE=true
# 资源公共路径,需要以 / 开头和结尾
VITE_PUBLIC_PATH=/
# 打包是否输出gz|br文件
# 可选: gzip | brotli | none
# 也可以有多个, 例如 ‘gzip’|'brotli',这样会同时生成 .gz和.br文件
VITE_BUILD_COMPRESS = 'gzip'
# 打包是否压缩图片
VITE_USE_IMAGEMIN = false
# 打包是否开启pwa功能
VITE_USE_PWA = false
# 是否兼容旧版浏览器。开启后打包时间会慢一倍左右。会多打出旧浏览器兼容包,且会根据浏览器兼容性自动使用相应的版本
VITE_LEGACY = false
测试配置
src\App.vue
<template>
<div>{{ vitePort }}</div>
</template>
<script lang="ts">
import { defineComponent, ref } from "vue";
export default defineComponent({
name: "App",
setup() {
const vitePort = ref(import.meta.env.VITE_PORT);
return {
vitePort,
};
},
});
</script>
生产环境动态配置
说明
当执行yarn build
构建项目之后,会自动生成_app.config.js
文件并插入index.html
。
注意:开发环境不会生成
// _app.config.js
// 变量名命名规则 __PRODUCTION__xxx_CONF__ xxx:为.env配置的VITE_GLOB_APP_SHORT_NAME
window.__PRODUCTION__VUE_VBEN_ADMIN__CONF__ = {
VITE_GLOB_APP_TITLE: 'vben admin',
VITE_GLOB_APP_SHORT_NAME: 'vue_vben_admin',
VITE_GLOB_API_URL: '/app',
VITE_GLOB_API_URL_PREFIX: '/',
VITE_GLOB_UPLOAD_URL: '/upload',
};
作用
_app.config.js
用于项目在打包后需要动态修改的需求,如接口地址, 不用重新进行打包,可在打包后通过修改/dist/_app.config.js
内的变量,刷新即可更新代码内的局部变量
如何获取全局变量
想要获取 _app.config.js
内的变量
可以使用src/hooks/setting/index.ts提供的函数来进行获取
如何新增(新增一个可动态修改的配置项)
首先在
.env
或者对应的开发环境配置文件内新增需要可动态配置的变量 需要以VITE_GLOB_
开头VITE_GLOB_
开头的变量会自动加入环境变量,通过在src/types/config.d.ts
内修改GlobEnvConfig
和GlobConfig
两个环境变量的值来定义新添加的类型useGlobSetting函数新增你刚才新增的返回值即可
const {
VITE_GLOB_APP_TITLE,
VITE_GLOB_API_URL,
VITE_GLOB_APP_SHORT_NAME,
VITE_GLOB_API_URL_PREFIX,
VITE_GLOB_UPLOAD_URL,
} = ENV;
export const useGlobSetting = (): SettingWrap => {
// Take global configuration
const glob: Readonly<GlobConfig> = {
title: VITE_GLOB_APP_TITLE,
apiUrl: VITE_GLOB_API_URL,
shortName: VITE_GLOB_APP_SHORT_NAME,
urlPrefix: VITE_GLOB_API_URL_PREFIX,
uploadUrl: VITE_GLOB_UPLOAD_URL
};
return glob as Readonly<GlobConfig>;
};
项目配置
WARNING
项目配置文件用于配置项目内展示的内容、布局、文本等效果,存于localStorage
中,在代码内更改之后需要清空localStorage
缓存
如果更改了项目配置,需要手动清空localStorage
缓存刷新重新登录后方可生效
配置文件路径
src/settings/projectSetting.ts
说明
// ! 改动后需要清空浏览器缓存
const setting: ProjectConfig = {
// 是否显示SettingButton
showSettingButton: true,
// 是否显示主题切换按钮
showDarkModeToggle: true,
// 设置按钮位置 可选项
// SettingButtonPositionEnum.AUTO: 自动选择
// SettingButtonPositionEnum.HEADER: 位于头部
// SettingButtonPositionEnum.FIXED: 固定在右侧
settingButtonPosition: SettingButtonPositionEnum.AUTO,
// 权限模式,默认前端角色权限模式
// ROUTE_MAPPING: 前端模式(菜单由路由生成,默认)
// ROLE:前端模式(菜单路由分开)
permissionMode: PermissionModeEnum.ROUTE_MAPPING,
// 权限缓存存放位置。默认存放于localStorage
permissionCacheType: CacheTypeEnum.LOCAL,
// 会话超时处理方案
// SessionTimeoutProcessingEnum.ROUTE_JUMP: 路由跳转到登录页
// SessionTimeoutProcessingEnum.PAGE_COVERAGE: 生成登录弹窗,覆盖当前页面
sessionTimeoutProcessing: SessionTimeoutProcessingEnum.ROUTE_JUMP,
// 项目主题色
themeColor: primaryColor,
// 网站灰色模式,用于可能悼念的日期开启
grayMode: false,
// 色弱模式
colorWeak: false,
// 是否取消菜单,顶部,多标签页显示, 用于可能内嵌在别的系统内
fullContent: false,
// 主题内容宽度
contentMode: ContentEnum.FULL,
// 是否显示logo
showLogo: true,
// 是否显示底部信息 copyright
showFooter: true,
// 头部配置
headerSetting: {
// 背景色
bgColor: '#ffffff',
// 固定头部
fixed: true,
// 是否显示顶部
show: true,
// 主题
theme: MenuThemeEnum.LIGHT,
// 开启锁屏功能
useLockPage: true,
// 显示全屏按钮
showFullScreen: true,
// 显示文档按钮
showDoc: true,
// 显示消息中心按钮
showNotice: true,
// 显示菜单搜索按钮
showSearch: true,
},
// 菜单配置
menuSetting: {
// 背景色
bgColor: '#273352',
// 是否固定住菜单
fixed: true,
// 菜单折叠
collapsed: false,
// 折叠菜单时候是否显示菜单名
collapsedShowTitle: false,
// 是否可拖拽
canDrag: true,
// 是否显示
show: true,
// 菜单宽度
menuWidth: 180,
// 菜单模式
mode: MenuModeEnum.INLINE,
// 菜单类型
type: MenuTypeEnum.SIDEBAR,
// 菜单主题
theme: MenuThemeEnum.DARK,
// 分割菜单
split: false,
// 顶部菜单布局
topMenuAlign: 'start',
// 折叠触发器的位置
trigger: TriggerEnum.HEADER,
// 手风琴模式,只展示一个菜单
accordion: true,
// 在路由切换的时候关闭左侧混合菜单展开菜单
closeMixSidebarOnChange: false,
// 左侧混合菜单模块切换触发方式
mixSideTrigger: MixSidebarTriggerEnum.CLICK,
// 是否固定左侧混合菜单
mixSideFixed: false,
},
// 多标签
multiTabsSetting: {
// 刷新后是否保留已经打开的标签页
cache: false,
// 开启
show: true,
// 开启快速操作
showQuick: true,
// 是否可以拖拽
canDrag: true,
// 是否显示刷新那妞
showRedo: true,
// 是否显示折叠按钮
showFold: true,
},
// 动画配置
transitionSetting: {
// 是否开启切换动画
enable: true,
// 动画名
basicTransition: RouterTransitionEnum.FADE_SIDE,
// 是否打开页面切换loading
openPageLoading: true,
//是否打开页面切换顶部进度条
openNProgress: false,
},
// 是否开启KeepAlive缓存 开发时候最好关闭,不然每次都需要清除缓存
openKeepAlive: true,
// 自动锁屏时间,为0不锁屏。 单位分钟 默认1个小时
lockTime: 0,
// 显示面包屑
showBreadCrumb: true,
// 显示面包屑图标
showBreadCrumbIcon: false,
// 是否使用全局错误捕获
useErrorHandle: false,
// 是否开启回到顶部
useOpenBackTop: true,
// 是否可以嵌入iframe页面
canEmbedIFramePage: true,
// 切换界面的时候是否删除未关闭的message及notify
closeMessageOnSwitch: true,
// 切换界面的时候是否取消已经发送但是未响应的http请求。
// 如果开启,想对单独接口覆盖。可以在单独接口设置
removeAllHttpPending: true,
};
缓存配置
用于配置缓存内容加密信息,对缓存到浏览器的信息进行 AES 加密
在/@/settings/encryptionSetting.ts内可以配置 localStorage
及 sessionStorage
缓存信息
前提 使用项目自带的缓存工具类 /@/utils/cache来进行缓存操作
import { isDevMode } from '/@/utils/env';
// 缓存默认过期时间
export const DEFAULT_CACHE_TIME = 60 * 60 * 24 * 7;
// 开启缓存加密后,加密密钥。采用aes加密
export const cacheCipher = {
key: '_11111000001111@',
iv: '@11111000001111_',
};
// 是否加密缓存,默认生产环境加密
export const enableStorageEncryption = !isDevMode();
多语言配置
用于配置多语言信息
在src/settings/localeSetting.ts内配置
export const LOCALE: { [key: string]: LocaleType } = {
ZH_CN: 'zh_CN',
EN_US: 'en',
};
export const localeSetting: LocaleSetting = {
// 是否显示语言选择器
showPicker: true,
// 当前语言
locale: LOCALE.ZH_CN,
// 默认语言
fallback: LOCALE.ZH_CN,
// 允许的语言
availableLocales: [LOCALE.ZH_CN, LOCALE.EN_US],
};
// 语言列表
export const localeList: DropMenu[] = [
{
text: '简体中文',
event: LOCALE.ZH_CN,
},
{
text: 'English',
event: LOCALE.EN_US,
},
];
主题色配置
默认全局主题色配置位于build/config/glob/themeConfig.ts内
只需要修改 primaryColor 为您需要的配色,然后重新执行yarn serve
即可
/**
* less global variable
*/
export const primaryColor = '#0960bd';
样式配置
css 前缀设置
用于修改项目内组件 class 的统一前缀
export const prefixCls = 'vben';
- 在src/design/var/index.less配置 css 前缀
@namespace: vben;
前缀使用
在 css 内
<style lang="less" scoped>
/* namespace已经全局注入,不需要额外在引入 */
@prefix-cls: ~'@{namespace}-app-logo';
.@{prefix-cls} {
width: 100%;
}
</style>
在 vue/ts 内
import { useDesign } from '/@/hooks/web/useDesign';
const { prefixCls } = useDesign('app-logo');
// prefixCls => vben-app-logo
样式检查
yarn add stylelint stylelint-config-standard stylelint-config-prettier stylelint-order -D
stylelint
是对我们编写的样式进行检查的插件。
stylelint-config-standard
是stylelint扩展的检查标准库。
stylelint-config-prettier
是用来解决冲突的(估计又和ESLint冲突了,参考之前的prettier)。
stylelint-order
是检查我们样式编写顺序的。
stylelint.config.js
module.exports = {
// ↓这个好像是没有用的,但是VbenAdmin是这么写的
root: true,
// ↓插件
plugins: ['stylelint-order'],
// ↓扩展
extends: ['stylelint-config-standard', 'stylelint-config-prettier'],
// ↓自定义规则
rules: {},
// ↓忽略检查的文件
ignoreFiles: ['**/*.js', '**/*.jsx', '**/*.tsx', '**/*.ts'],
};
module.exports = {
// ...
rules: {
// ↓禁止使用未知的伪类选择器。
'selector-pseudo-class-no-unknown': [
true,
{
ignorePseudoClasses: ['global'],
},
],
// ↓禁止使用未知规则。
'at-rule-no-unknown': [
true,
{
ignoreAtRules: ['function', 'if', 'each', 'include', 'mixin'],
},
],
// ↓禁止空来源。
'no-empty-source': null,
// ↓禁止使用无效的命名网格区域。
'named-grid-areas-no-invalid': null,
// ↓要求或不允许使用Unicode字节顺序标记。
'unicode-bom': 'never',
// ↓禁止较低特异性的选择器在覆盖较高特异性的选择器之后出现。
'no-descending-specificity': null,
// ↓禁止在字体系列名称列表中缺少通用系列。
'font-family-no-missing-generic-family-keyword': null,
// ↓在声明的冒号后面需要一个空格或禁止空格。
'declaration-colon-space-after': 'always-single-line',
// ↓在声明的冒号之前需要一个空格或禁止使用空格。
'declaration-colon-space-before': 'never',
// ↓在声明块内要求或不允许尾随分号。
'declaration-block-trailing-semicolon': 'always',
// ↓在规则之前要求或禁止使用空行。
'rule-empty-line-before': [
'always',
{
ignore: ['after-comment', 'first-nested'],
},
],
// ↓禁止使用未知单位。
'unit-no-unknown': [true, { ignoreUnits: ['rpx'] }],
// Specify the alphabetical order of the attributes in the declaration block
// ↓样式顺序
'order/properties-order': [
'position',
'top',
'right',
'bottom',
'left',
'z-index',
'display',
'float',
...
],
},
// ...
};
.stylelintignore
/dist/*
/public/*
public/*
PostCSS
安装两个库postcss
、autoprefixer
。要现实的效果就是我们编写一般的样式,渲染都页面的dom节点有面向各种浏览器厂商的样式。
postcss
就像一个管子。autoprefixer
是里面的过滤器。你写的css
从管子中流过,经过他们的处理就出现了不同的结果。
yarn add postcss autoprefixer -D
postcss.config.js
module.exports = {
plugins: {
autoprefixer: {},
},
};
颜色配置
用于预设一些颜色数组
在src/settings/designSetting.ts内配置
// app主题色预设
export const APP_PRESET_COLOR_LIST: string[] = [
'#0960bd',
'#0084f4',
'#009688',
'#536dfe',
'#ff5c93',
'#ee4f12',
'#0096c7',
'#9c27b0',
'#ff9800',
];
// 顶部背景色预设
export const HEADER_PRESET_BG_COLOR_LIST: string[] = [
'#ffffff',
'#009688',
'#5172DC',
'#1E9FFF',
'#018ffb',
'#409eff',
'#4e73df',
'#e74c3c',
'#24292e',
'#394664',
'#001529',
'#383f45',
];
//左侧菜单背景色预设
export const SIDE_BAR_BG_COLOR_LIST: string[] = [
'#001529',
'#273352',
'#ffffff',
'#191b24',
'#191a23',
'#304156',
'#001628',
'#28333E',
'#344058',
'#383f45',
];
组件默认参数配置
在src/settings/componentSetting.ts内配置
// 用于配置某些组件的常规配置,而无需修改组件
import type { SorterResult } from '../components/Table';
export default {
// 表格配置
table: {
// 表格接口请求通用配置,可在组件prop覆盖
// 支持 xxx.xxx.xxx格式
fetchSetting: {
// 传给后台的当前页字段
pageField: 'page',
// 传给后台的每页显示多少条的字段
sizeField: 'pageSize',
// 接口返回表格数据的字段
listField: 'items',
// 接口返回表格总数的字段
totalField: 'total',
},
// 可选的分页选项
pageSizeOptions: ['10', '50', '80', '100'],
//默认每页显示多少条
defaultPageSize: 10,
// 默认排序方法
defaultSortFn: (sortInfo: SorterResult) => {
const { field, order } = sortInfo;
return {
// 排序字段
field,
// 排序方式 asc/desc
order,
};
},
// 自定义过滤方法
defaultFilterFn: (data: Partial<Recordable<string[]>>) => {
return data;
},
},
// 滚动组件配置
scrollbar: {
// 是否使用原生滚动样式
// 开启后,菜单,弹窗,抽屉会使用原生滚动条组件
native: false,
},
};
vite路径参数配置
src\main.ts
import router, { setupRouter } from "/@/router";
vite.config.ts
export default ({ command, mode }: ConfigEnv): UserConfig => {
return {
base: VITE_PUBLIC_PATH,
root,
resolve: {
alias: [
// /@/xxxx => src/xxxx
{
find: /\/@\//,
replacement: pathResolve('src') + '/',
},
// /#/xxxx => types/xxxx
{
find: /\/#\//,
replacement: pathResolve('types') + '/',
},
// ['@vue/compiler-sfc', '@vue/compiler-sfc/dist/compiler-sfc.esm-browser.js'],
],
},
tsconfig.json
{
"compilerOptions": {
...
"baseUrl": ".",
"paths": {
"/@/*": ["src/*"],
"/#/*": ["types/*"]
}
},