Mobile + Vue = MobVue

# 简介 [MobVue](https://github.com/un-pany/mobvue) 是一个精心制作的移动端 H5 模板，基于 Vue3、Vite、TypeScript、Vant 等主流技术 # 使用 *点击展开*

推荐环境

* 新版 `Visual Studio Code` 或者 AI IDE `Cursor` 与 `Trae` * 安装 `.vscode/extensions.json` 文件中推荐的插件 * `node` 20.19+ 或 22.12+ * `pnpm` 10+ * `bun` 最新的

本地开发

使用 `Node` + `pnpm` ```bash # 安装依赖 pnpm i # 启动服务 pnpm dev ``` 使用 `Bun` ```bash bun i bun run dev ```

打包构建

使用 `Node` + `pnpm` ```bash # 打包构建预发布环境 pnpm build:staging # 打包构建生产环境 pnpm build ``` 使用 `Bun` ```bash bun run build:staging bun run build ```

本地预览

使用 `Node` + `pnpm` ```bash # 先执行打包构建命令生成 dist 目录后再执行以下预览命令 pnpm preview ``` 使用 `Bun` ```bash bun run preview ```

代码检查

使用 `Node` + `pnpm` ```bash # 代码校验与格式化 pnpm lint # 单元测试 pnpm test ``` 使用 `Bun` ```bash bun run lint bun run test ```

代码提交规范

`feat` 新功能 `fix` 修复错误 `perf` 性能优化 `refactor` 重构代码 `docs` 文档和注释 `types` 类型相关 `test` 单测相关 `ci` 持续集成、工作流 `revert` 撤销更改 `chore` 琐事（更新依赖、修改配置等）

# 特性 🔥 最新的 [语法](https://vuejs.org/api/sfc-script-setup.html)、[配置](https://github.com/un-pany/mobvue/blob/main/vite.config.ts)、[依赖](https://github.com/un-pany/mobvue/blob/main/package.json) 📍 [纯一级路由设计](https://github.com/un-pany/mobvue/blob/main/src/router/index.ts) - 清晰且缓存友好 📱 移动端适配 [px2vw](https://github.com/un-pany/mobvue/blob/main/postcss.config.ts) - 并且宽屏友好 🌐 浏览器适配 [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) + [autoprefixer](https://github.com/postcss/autoprefixer) + [browserslist](https://github.com/browserslist/browserslist) - 兼容多种浏览器和低版本浏览器 🧩 [布局系统](https://github.com/un-pany/mobvue/blob/main/src/layout) - 配置化的 🔒 权限控制 [页面级](https://github.com/un-pany/mobvue/blob/main/src/router/guard.ts)、[按钮级](https://github.com/un-pany/mobvue/blob/main/src/pages/demo/permission.vue) 🌗 主题模式 [Dark Mode](https://github.com/un-pany/mobvue/blob/main/src/common/assets/styles/variables.css) 🫧 [拥抱原子化 CSS](https://github.com/un-pany/mobvue/blob/main/uno.config.ts) 📲 [PWA](https://github.com/antfu/vite-plugin-pwa) - 渐进式 Web 应用 🔧 [组件](https://github.com/unplugin/unplugin-vue-components) 和 [API](https://github.com/unplugin/unplugin-auto-import) 自动按需导入 🔎 [Husky](https://github.com/un-pany/mobvue/blob/main/.husky/pre-commit) + [lint-staged](https://github.com/un-pany/mobvue/blob/main/package.json) + [ESLint](https://github.com/un-pany/mobvue/blob/main/eslint.config.js) - 规范代码 💪🏻 依然 [TypeScript](https://github.com/un-pany/mobvue/blob/main/tsconfig.json) - 严格模式且无 `any` 👀 更多功能 - [路由缓存](https://github.com/un-pany/mobvue/blob/main/src/pinia/stores/keep-alive.ts)、[带防御的水印](https://github.com/un-pany/mobvue/blob/main/src/common/composables/useWatermark.ts)、[灰色和色弱模式](https://github.com/un-pany/mobvue/blob/main/src/common/composables/useGrayscaleAndColorblind.ts)、[SVG Loader](https://github.com/jpkleemans/vite-svg-loader)、[VConsole](https://github.com/un-pany/mobvue/blob/main/src/plugins/console.ts)、[白屏加载动画](https://github.com/un-pany/mobvue/blob/main/public/app-loading.css)、[单元测试](https://github.com/un-pany/mobvue/blob/main/tests)、[国际化](https://github.com/un-pany/mobvue/blob/main/src/plugins/i18n.ts) # 技术栈 **Vue3**：采用 Vue3 + script setup 最新的 Vue3 组合式 API **Vant**：轻量、可定制的移动端 Vue 组件库 **Pinia**: 传说中的 Vuex5 **Vite**：真的很快 **Vue Router**：路由路由 **TypeScript**：JavaScript 语言的超集 **pnpm**：更快速的，节省磁盘空间的包管理工具 **ESLint**：代码校验与格式化 **Axios**：发送网络请求（已封装好） **UnoCSS**：具有高性能且极具灵活性的即时原子化 CSS 引擎 **Bun**：一款快速的 JavaScript 运行时 # 目录结构 ```sh # mobvue ├─ .husky # commit 时进行代码校验和格式化 ├─ .vscode # vscode 配置和插件 ├─ public │ ├─ favicon.png # 网站头像 │ └─ app-loading.css # 首屏 loading 动画 ├─ src │ ├─ common # 通用目录 │ │ ├─ apis # 通用目录 - 接口 │ │ ├─ assets # 通用目录 - 静态资源 │ │ ├─ components # 通用目录 - 组件 │ │ ├─ composables # 通用目录 - 组合式函数 │ │ ├─ constants # 通用目录 - 常量 │ │ └─ utils # 通用目录 - 工具函数 │ ├─ http # 网络请求 │ ├─ layout # 布局 │ ├─ pages # 页面 │ │ └─ login # 登录模块 │ │ ├─ apis # 登录模块 - 私有接口 │ │ ├─ components # 登录模块 - 私有组件 │ │ ├─ composables # 登录模块 - 私有组合式函数 │ │ ├─ images # 登录模块 - 私有图片 │ │ └─ index.vue # 登录模块 - 页面 │ ├─ pinia # 状态管理 │ ├─ plugins # 插件（全局组件、自定义指令等） │ ├─ router # 路由 │ ├─ App.vue # 入口页面 │ └─ main.ts # 入口文件 ├─ tests # 单元测试 ├─ types # 类型声明 ├─ .editorconfig # 编辑器配置 ├─ .env # 所有环境 ├─ .env.development # 开发环境 ├─ .env.production # 生产环境 ├─ .env.staging # 预发布环境 ├─ eslint.config.js # eslint 配置 ├─ tsconfig.json # ts 配置 ├─ uno.config.ts # unocss 配置 └─ vite.config.ts # vite 配置 ``` # 基础 ## 移动端适配 ***rem or vw? Of course, vw!*** 基于 [postcss](https://github.com/postcss/postcss) + [postcss-mobile-forever](https://github.com/wswmsword/postcss-mobile-forever)，实现 `px` 到 `vw` 的自动转化具体内置的配置如下： ```ts { // UI 设计稿宽度 viewportWidth: (file: string) => file.includes("vant") ? 375 : 375, // 限制视图的最大宽度 maxDisplayWidth: 750, // 页面最外层选择器 appSelector: "#app", // 是否对「页面最外层选择器」对应的元素进行描边 border: true, // 转换单位后保留的小数点位数 unitPrecision: 3, // 转换后的单位 mobileUnit: "vw", // 需要转换的属性 propList: ["*"], // 忽略的选择器 selectorBlackList: [".ignore", "keep-px"], // 忽略的属性 propertyBlackList: { ".van-icon": "font" }, // 忽略的属性值 valueBlackList: ["1px"], // 忽略的目录或文件 exclude: [], // 包含块是根元素的选择器列表 rootContainingBlockSelectorList: ["van-tabbar", "van-popup"] } ``` ## 浏览器适配基于 [@vitejs/plugin-legacy](https://github.com/vitejs/vite/tree/main/packages/plugin-legacy) + [autoprefixer](https://github.com/postcss/autoprefixer) + [browserslist](https://github.com/browserslist/browserslist) 兼容多种浏览器和低版本浏览器你可以无感的使用这套内置的配置，唯一可能需要你改动的地方，可能是 `package.json` 文件里面的 `browserslist` 配置，它默认是这样的： ```json "browserslist": [ "defaults" ] ``` 你可以根据自己想兼容的浏览器来修改这个地方 ## 路由设计 ### 纯一级路由 📍 **无需设置嵌套路由来实现 Layout 布局，路由配置更加清晰简洁，并且对路由缓存更加友好，告别某些场景下缓存失效的问题！** 如果不需要显示 `Layout` 布局，以**登录页面**为例，你可以这样配置： ```ts { path: "/login", component: () => import("@/pages/login/index.vue"), name: "Login", meta: { title: "登录" } } ```

如果需要 `Layout` 布局，以**我的页面**为例，你可以这样配置： ```ts { path: "/me", component: () => import("@/pages/me/index.vue"), name: "Me", meta: { title: "我的", layout: { navBar: { showNavBar: true, showLeftArrow: false }, tabbar: { showTabbar: true, icon: "user-o" }, footer: true } } } ```

### meta 配置项 ```ts { /** * @description 页面标题 */ title?: string /** * @description 设置能进入该路由的角色，支持多个角色叠加，默认不限制角色 * @default undefined */ roles?: string[] /** * @description 是否缓存该路由页面，注意路由和页面都需要设置一致的 Name * @default false */ keepAlive?: boolean /** * @description 布局配置 */ layout?: { /** * @description NavBar 配置 */ navBar?: { /** * @description 是否显示 NavBar * @default false */ showNavBar?: boolean /** * @description 是否显示左侧箭头 * @default false */ showLeftArrow?: boolean } tabbar?: { /** * @description 是否显示 Tabbar * @default false */ showTabbar?: boolean /** * @description 图标 */ icon?: string } /** * @description 是否显示 Footer * @default false */ footer?: boolean } } ``` ## 权限控制 ### 页面级控制代码都在路由守卫 `@/router/guard.ts` 中，这里可根据具体的业务做相应的修改： ```ts NProgress.configure({ showSpinner: false }) const { setTitle } = useTitle() const LOGIN_PATH = "/login" export function registerNavigationGuard(router: Router) { // 全局前置守卫 router.beforeEach((to, _from) => { NProgress.start() const userStore = useUserStore() // 如果没有登录 if (!getToken()) { // 如果在免登录的白名单中，则直接进入 if (isWhiteList(to)) return true // 其他没有访问权限的页面将被重定向到登录页面 return LOGIN_PATH } // 如果已经登录，并准备进入 Login 页面，则重定向到主页 if (to.path === LOGIN_PATH) return "/" // 判断有无该页面权限 if (to.meta.roles ? userStore.roles.some(role => to.meta.roles!.includes(role)) : true) return true // 无权限则进入 403 页面 return "/403" }) // 全局后置钩子 router.afterEach((to) => { const keepAliveStore = useKeepAliveStore() // 清除所有路由缓存 if (to.path === LOGIN_PATH) keepAliveStore.delAllCachedRoutes() // 添加路由缓存 keepAliveStore.addCachedRoute(to) // 设置标题 setTitle(to.meta.title) NProgress.done() }) } ``` ### 按钮级基于**权限指令**和**权限函数**两种方式实现按钮级权限控制： ```html

``` 其中的关键代码只有两行： ```html // 权限指令 v-permission="['admin']" // 权限函数 v-if="checkPermission(['admin'])" ``` ## 发送 HTTP 请求大致的流程如下： ```mermaid graph LR 页面/交互 --> api --> axios --> 服务器 ``` ### 通用 API 模块 `src/common/apis` 目录存放通用的接口，而非某个页面固定使用的接口 ### 私有 API 模块某个页面固定使用的接口，应该在当前页面目录下建立一个 `apis` 文件夹，用来存放私有接口参考登录页 `src/pages/login/apis` ### 封装的 Axios `src/http/axios.ts` 是基于 axios 的封装，封装了全局 request 拦截器、response 拦截器、统一的错误处理、统一的超时处理、baseURL 设置等 ## 多环境 ### 打包构建项目开发完成，打包构建代码时，内置两种环境： ```sh # 打包构建预发布环境 pnpm build:staging # 打包构建生产环境 pnpm build ``` ### 环境变量在 `.env.production` 等形如 `.env.xxx` 文件中，配置了该环境对应的一些环境变量，例如： ```sh ## 后端接口地址（如果解决跨域问题采用反向代理就只需写相对路径） VITE_BASE_URL = /api/v1 ## 开发环境域名和静态资源公共路径（一般 / 或 ./ 都可以） VITE_PUBLIC_PATH = / ``` 使用方式： ```ts console.log(import.meta.env.VITE_BASE_API) ``` # 进阶 ## ESLint 规范代码很重要！ * 配置项在 `eslint.config.js` 文件中 * 推荐安装 VSCode 的 `ESLint` 插件，它可在写代码时，将不符合规范的代码标红，并且在你保存代码时自动修复一些简单的标红的代码 * 手动校验和格式化命令 `pnpm lint`（提交代码前可以执行该命令） ## 代码提交校验项目采用 `husky` + `lint-staged` 的方式，在提交代码的时候，进行全局 `ts` 类型检查和 `eslint` 校验 `husky` 会自动初始化，如果发现没有正常初始化，也可以通过命令 `pnpm prepare` 初始化 `husky` ## 跨域 ### 反向代理 `vite.config` 里有 `proxy` 进行反向代理，与之对应的生产环境，则可以使用 `nginx` 来做反向代理 ```ts proxy: { "/api/v1": { target: "https://xxxxxx", // 是否为 WebSocket ws: false, // 是否允许跨域 changeOrigin: true } } ``` ### CORS 这种方案对于前端来说没有什么工作量，和正常发送请求写法上没有任何区别，工作量基本都在后端这里实现 [CORS](http://www.ruanyifeng.com/blog/2016/04/cors.html) 之后，不管是开发环境还是生产环境，都能方便的调用接口 ## SVG `vite-svg-loader` 插件提供的的能力，可以将 SVG 文件导入为 Vue 组件！比如 404 页面： ```ts ``` ## 自动按需导入基于 [unplugin-vue-components](https://github.com/unplugin/unplugin-vue-components) 和 [unplugin-auto-import](https://github.com/unplugin/unplugin-auto-import) 实现的组件和 API 自动按需导入如果我们要使用 `Vant` 的按钮组件，例如 `van-button`，不用再手动通过 `import` 语句导入组件和样式，而是可以直接使用： ```html 主要按钮 ``` 如果我们要使用 Vue 的 `ref` API，也不用再手动导入，直接使用即可： ```ts const loading = ref(false) ``` *所有已经内置的自动按需导入：`vue`、`vue-router`、`pinia`、`vant` 相关的 API 和组件，它们四个会自动按需导入，切记不要手动 `import`* ## 自动生成类型 `types/auto` 目录下为自动生成的类型，无需手动管理，切记不要手动修改 # 常见问题 ## 报错 * AI 一下可以解决 `99%` 的报错 * 尝试删除 `node_modules` 和 `.lock` 文件后再次依赖 * 检查环境是否和作者推荐的一致 * 重启一下？ ## 依赖超时 * 国内用户可以设置最新的淘宝源加快依赖速度 `https://registry.npmmirror.com` ## 热更新失效 * 检查配置路由时填写的路径是否正确（特别是字母大小写问题） ## 本地开发时切换路由导致页面重载 *只会在开发环境出现，不会影响生成环境* * 由 `unplugin-vue-components` 导致的问题，可等待插件修复 * 也可以取消自动按需导入样式，改为自己手动全量导入 `Vant` 样式来解决该问题 # 预览图 ![image.png](https://p9-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/712ed39c153e41f4a8adb39154c35151~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAgcGFueQ==:q75.awebp?rk3s=f64ab15b&x-expires=1774568085&x-signature=A3P6Ls22zPPwug%2BNTc3jAef3Wxo%3D) # 相关链接 **在线预览**：[github-pages](https://un-pany.github.io/mobvue) **GitHub 仓库**：[github](https://github.com/un-pany/mobvue) **Gitee 仓库**：[gitee](https://gitee.com/un-pany/mobvue) **交流群**：[查看进群方式](https://github.com/un-pany/mobvue/issues/3) **发行版 & 更新日志**：[releases](https://github.com/un-pany/mobvue/releases)