目录说明

<code>

.

├── build # 打包脚本相关

│ ├── config # 配置文件

│ ├── generate # 生成器

│ ├── script # 脚本

│ └── vite # vite配置

├── mock # mock文件夹

├── public # 公共静态资源目录

├── src # 主目录

│ ├── api # 接口文件

│ ├── assets # 资源文件

│ │ ├── icons # icon sprite 图标文件夹

│ │ ├── images # 项目存放图片的文件夹

│ │ └── svg # 项目存放svg图片的文件夹

│ ├── components # 公共组件

│ ├── design # 样式文件

│ ├── directives # 指令

│ ├── enums # 枚举/常量

│ ├── hooks # hook

│ │ ├── component # 组件相关hook

│ │ ├── core # 基础hook

│ │ ├── event # 事件相关hook

│ │ ├── setting # 配置相关hook

│ │ └── web # web相关hook

│ ├── layouts # 布局文件

│ │ ├── default # 默认布局

│ │ ├── iframe # iframe布局

│ │ └── page # 页面布局

│ ├── locales # 多语言

│ ├── logics # 逻辑

│ ├── main.ts # 主入口

│ ├── router # 路由配置

│ ├── settings # 项目配置

│ │ ├── componentSetting.ts # 组件配置

│ │ ├── designSetting.ts # 样式配置

│ │ ├── encryptionSetting.ts # 加密配置

│ │ ├── localeSetting.ts # 多语言配置

│ │ ├── projectSetting.ts # 项目配置

│ │ └── siteSetting.ts # 站点配置

│ ├── store # 数据仓库

│ ├── utils # 工具类

│ └── views # 页面

├── types # 类型文件

└── vite.config.ts # vite配置文件

项目配置项

用于修改项目的配色、布局、缓存、多语言、组件默认配置

#环境变量配置

项目的环境变量配置位于项目根目录下的 .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配置文件当中.

#配置项说明

#.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"]]

::: tip

v3.0.0开始，作者重构了vite.config.ts，新版本不再支持VITE_PROXY环境变量。

:::

# 接口地址

# 如果没有跨域问题，直接在这里配置即可

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

#生产环境动态配置

#说明

当执行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_ 开头的变量会自动加入环境变量，通过在 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 缓存，刷新重新登录后方可生效。

#配置文件路径

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 的统一前缀

在 src/settings/designSetting.ts 内配置

export const prefixCls = 'vben';

在 src/design/var/index.less 配置 css 前缀

@namespace: vben;

#前缀使用

在 css 内

<style lang="less" scoped>code>

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

#颜色配置