Repository navigation
本次为基础设施现代化改造,包含破坏性变更,升级前请阅读下方"破坏性变更"。
🚀 包体优化(首屏 gzip:默认 458KB,关闭 mock 后 239KB,预算 500KB)
- mock 可一键摇掉:本项目定位为面向开发者的演示模板,
.env.production默认VITE_USE_MOCK=true以保留无后端演示能力;接入真实后端时改为false,@faker-js/faker+mockjs等 mock 依赖(约 220KB gzip)会被完整摇掉,首屏 gzip 458KB → 239KB - 删除 naive-ui 全局注册(
src/plugins/naive.ts):此前 66 个组件被整包注册,unplugin-vue-components的按需引入完全失效 - 重写分包策略:
manualChunks由「整库成块」改为只固定框架基座,naive-ui 与业务模块按路由自然分割,避免 1MB 的 naive-ui 块被入口同步引用 - echarts 精简按需注册:只保留 Bar / Line / Pie 与 Grid / Tooltip / Legend / Title,其余图表与组件改为注释可选(817KB → 578KB)
- 新增
scripts/report-bundle-size.mjs:统计首屏静态闭包体积(含 gzip / brotli),支持BUNDLE_BUDGET_KB体积预算,pnpm build后自动输出 - 新增
pnpm size/pnpm report(rollup-plugin-visualizer输出到.analyze/) - CI 增加体积预算校验:首屏 gzip 超过 500KB 直接失败
🌍 国际化(i18n)
- 接入
vue-i18n@11,内置zh-CN/en-US;顶栏新增语言切换入口,选择持久化到localStorage,首次访问按浏览器语言推断 naive-ui的locale/date-locale跟随当前语言切换(日期选择器、空状态等组件文案同步)- 路由菜单国际化:
src/router/modules/*.ts的meta.title改为 i18n key(如route.dashboard_console),侧边菜单 / 面包屑 / 多页签统一翻译,切换语言即时生效 - 后端返回的动态菜单若仍是中文标题,未命中语言包时原样回显,不会把 key 暴露给用户
- 语言包拆分到
src/locales/lang/<locale>,默认语言(zh-CN)随首屏加载,其余语言按需异步加载,不影响首屏体积 - 英文语言包使用
satisfies typeof zhMessages约束,漏翻会在pnpm type-check阶段直接报错 - 已翻译范围:菜单与框架层(顶栏、多页签、项目配置面板、登录页、关于页)、浏览器标签页标题;页脚组件当前版本未启用;业务页面与
src/components扩展组件保持原样,由使用方按需接入(README「国际化」章节有接入示例) - 修复菜单不翻译:
NMenuOption渲染的是 option 的title字段而非label,菜单对象由...meta展开后title仍是 i18n key,导致侧边菜单始终显示route.xxx;现label与title统一赋翻译后的文案 - 修复首次切换语言时侧边菜单不刷新:
setLocale先更新 Pinia 状态、后加载语言包,菜单 watcher 会在 i18n 切到新语言前触发;现改为先await语言包加载与 i18n 切换,再更新响应式状态 - 修复浏览器标签页标题显示 i18n key(
router/guards.ts中document.title现走tr()) - 后端动态菜单不再在登录时预翻译:
src/router/generator.ts保留后端返回的原始meta.title,菜单/面包屑渲染时再翻译,因此 BACK 模式下切换语言也能实时生效;纯中文标题未命中语言包时原样回显 - 项目配置面板的动画类型下拉改为按当前语言显示(
layout.setting.animate.*)
🎨 登录页重构
- 重新设计
src/views/login/index.vue:由「居中浮空卡片 + 全屏装饰动画」改为「左侧品牌区 / 右侧表单区」的分栏布局 - 移除全部装饰元素与动效:波浪、漂浮几何图形、按钮 ripple、卡片悬浮位移、
animate.css入场类(依赖本就未安装,类名无效) - 主题联动:通过
useThemeVars()把主题色 / 背景色 / 边框色透传为 CSS 变量,登录页自动跟随系统主题色与深色模式 - 表单增强:回车提交、用户名自动聚焦(改用
NInput实例focus(),不再querySelector)、按钮 loading 防重复提交、请求异常兜底提示 - 小屏(< 960px)自动收起品牌区,只保留居中表单卡片
✨ 工程化
- 新增
type-check脚本(vue-tsc --noEmit),项目历史上第一次真正做类型检查 - 新增 GitHub Actions CI(安装依赖 → 类型检查 → ESLint → Stylelint → 构建)
- 新增
eslint.config.mjs(ESLint 10 flat config),删除.eslintrc.js/.eslintignore - 新增
commitlint.config.cjs、.cz-config.js,补装缺失的cz-customizable - 新增
.husky钩子(pre-commit跑 lint-staged、commit-msg跑 commitlint),并补上prepare脚本 - 新增
pnpm-workspace.yaml,声明allowBuilds(esbuild),解决新版 pnpm 默认拦截构建脚本导致装完跑不起来的问题 - 修复
build脚本依赖了未声明的chalk、fs-extra(此前靠依赖提升侥幸可用)
⬆️ 依赖升级
vite5.4 → 7.3,@vitejs/plugin-vue3.2 → 6.0,@vitejs/plugin-vue-jsx2.1 → 5.1typescript4.9 → 5.9,新增vue-tsc3.3eslint8 → 10、stylelint14 → 17(补postcss-html/postcss-less)、prettier2 → 3unplugin-vue-components0.22 → 32、husky8 → 9、lint-staged13 → 17、commitlint17 → 21、rimraf3 → 6、gh-pages4 → 6vue3.5.21 → 3.5.44、naive-ui2.43 → 2.45、vue-router→ 4.6、alova→ 3.5、@vueuse/core9 → 15、echarts5 → 6、date-fns2 → 4
🐛 修复
- 移除
vue-types:vue-types@4会破坏 Vue 3.5 的 props 类型推断,导致BasicTable可编辑单元格等组件 props 全部塌成{} - 修复
BasicUpload读取了不存在的globSetting.imgUrl(应为fileUrl),图片地址拼接一直是错的 - 修复生产环境
.env.production仍使用旧变量名VITE_GLOB_IMG_URL(代码读取的是VITE_GLOB_FILE_URL),导致上传/图片前缀为undefined - 清理
types/global.d.ts中已废弃的VITE_GLOB_PROD_MOCK/VITE_GLOB_IMG_URL声明,补充VITE_GLOB_FILE_URL tsconfig.json的 include 指向vite.config.mts,修复配置文件类型检查被跳过- 登录页、关于页、登录/404 路由标题接入 i18n;关于页版本号与技术栈描述更新为当前实际(Vue 3 / Vite 7 / TypeScript),预览站点链接修正为
gratis.naiveadmin.com - 修复
CreateDrawer未暴露openDrawer,父组件通过 ref 调用在部分场景失效 - 修复
zoom.less中transition: opacity 0.1(缺单位) - 修复登录后锁屏定时器类型导致的
clearInterval重载错误 - 修复
downloadFile中canvas.toBlob返回 null 时的空指针 - 清理
BasicSetting/EmailSetting/RevealSetting/system.vue中的未使用导入与死代码
💥 破坏性变更
- 路由
meta.title语义变更:由中文文案改为 i18n key(如'主控台'→'route.dashboard_console')。自定义路由请同步调整,或在src/locales/lang/<locale>/route.ts中补上对应词条 vite.config.ts改名为vite.config.mts(体积分析插件为纯 ESM,需以 ESM 方式加载配置)- 默认构建携带 mock:
.env.production的VITE_USE_MOCK默认true(面向开发者演示,无需后端即可跑通)。接入真实后端时请改为false并配置VITE_GLOB_API_URL;pnpm build即演示包,无需额外的 demo 配置 - 品牌变量调整:
.env中VITE_GLOB_APP_TITLE为Naive Ui Admin、VITE_GLOB_APP_SHORT_NAME为NaiveAdmin。浏览器标签标题随之变化;VITE_GLOB_APP_SHORT_NAME同时决定生产环境app.config.js的全局变量名,请与部署侧保持一致 - Node 要求提升到
>=20.19.0,pnpm 要求>=10 - 删除
src/utils/propTypes.ts及vue-types依赖,请改用 Vue 原生 props 声明 - 依赖
dayjs被移除(统一使用date-fns);qs、vue-draggable-next、jest等未使用依赖一并移除 - ESLint 配置改为 flat config(不再读取
.eslintrc.js)