{"id":13457591,"url":"https://github.com/yulimchen/vue3-h5-template","last_synced_at":"2025-05-14T18:02:10.392Z","repository":{"id":37357395,"uuid":"226095363","full_name":"yulimchen/vue3-h5-template","owner":"yulimchen","description":"🌱 A ready-to-use mobile project base template built with the Vue3, Vant, and Vite. | 基于 Vue3、Vite5、TypeScript/JavaScript、Tailwindcss、Vant4，开箱即用的移动端项目基础模板","archived":false,"fork":false,"pushed_at":"2024-12-02T14:55:10.000Z","size":7071,"stargazers_count":1247,"open_issues_count":4,"forks_count":292,"subscribers_count":15,"default_branch":"master","last_synced_at":"2025-04-13T16:50:39.937Z","etag":null,"topics":["app","demo","eruda","h5","i18n","iconify","javascript","js","mobile","pinia","starter","tailwindcss","template","ts","typescript","vant","vite","vmin","vue","vue3"],"latest_commit_sha":null,"homepage":"https://yulimchen.github.io/vue3-h5-template/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/yulimchen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-12-05T12:17:33.000Z","updated_at":"2025-04-12T06:21:05.000Z","dependencies_parsed_at":"2023-01-28T21:15:14.174Z","dependency_job_id":"d10c93d3-36e2-4388-9eb9-0849f7714615","html_url":"https://github.com/yulimchen/vue3-h5-template","commit_stats":null,"previous_names":[],"tags_count":12,"template":true,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yulimchen%2Fvue3-h5-template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yulimchen%2Fvue3-h5-template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yulimchen%2Fvue3-h5-template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/yulimchen%2Fvue3-h5-template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/yulimchen","download_url":"https://codeload.github.com/yulimchen/vue3-h5-template/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254198453,"owners_count":22030964,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["app","demo","eruda","h5","i18n","iconify","javascript","js","mobile","pinia","starter","tailwindcss","template","ts","typescript","vant","vite","vmin","vue","vue3"],"created_at":"2024-07-31T09:00:30.889Z","updated_at":"2025-05-14T18:02:10.314Z","avatar_url":"https://github.com/yulimchen.png","language":"TypeScript","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"readme":"\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\t\u003cimg src=\"docs/assets/img/banner.jpg\" alt=\"banner\" /\u003e\r\n\u003c/div\u003e\r\n\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\t\u003ca href=\"https://github.com/yulimchen/vue3-h5-template/blob/master/LICENSE\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/github/license/yulimchen/vue3-h5-template.svg?style=flat-square\" alt=\"license\"\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://github.com/yulimchen/vue3-h5-template/releases\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/github/release/yulimchen/vue3-h5-template.svg?style=flat-square\" alt=\"GitHub release\"\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://github.com/yulimchen/vue3-h5-template\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/github/stars/yulimchen/vue3-h5-template?style=flat-square\" alt=\"GitHub stars\"\u003e\r\n  \u003c/a\u003e\r\n  \u003ca href=\"https://github.com/yulimchen/vue3-h5-template\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/github/forks/yulimchen/vue3-h5-template?style=flat-square\" alt=\"GitHub forks\"\u003e\r\n  \u003c/a\u003e\r\n\u003c/div\u003e\r\n\r\n\r\n\u003ch1 align=\"center\"\u003eVue3 H5 Template\u003c/h1\u003e\r\n\r\n**🌱 基于 Vue3 全家桶、TS/JS、Vite 构建工具，开箱即用的移动端项目基础模板**\r\n\r\n- [x] ⚡ Vue3 + Vite5\r\n- [x] 🍕 TypeScript\r\n- [x] ✨ Vant4 组件库\r\n- [x] 🌀 Tailwindcss 原子类框架\r\n- [x] 👏 集成多种图标方案\r\n- [x] 🍍 Pinia 状态管理\r\n- [x] 🌓 支持深色模式\r\n- [x] 🧀 支持 i18n\r\n- [x] Vue-router 4\r\n- [x] vmin 视口适配\r\n- [x] Axios 封装\r\n- [x] 打包资源 gzip 压缩\r\n- [x] 开发环境支持 Mock 数据\r\n- [x] ESLint\r\n- [x] 首屏加载动画\r\n- [x] 开发环境调试面板\r\n- [x] 生产环境 CDN 依赖\r\n\r\n**如有 i18n 国际化多语言需求，请切换到 [i18n](https://github.com/yulimchen/vue3-h5-template/tree/i18n) 分支**\r\n\r\n**主分支默认 TypeScript，如果你希望使用的是 JavaScript 语言，请切换 [js-version](https://github.com/yulimchen/vue3-h5-template/tree/js-version) 分支进行开发**\r\n\r\n\r\n\r\n## 在线预览 Preview\r\n\r\n👓 [点击这里](https://yulimchen.github.io/vue3-h5-template/)（PC浏览器请切换手机端模式）\r\n\r\n\r\n\r\n## 运行项目\r\n\r\n注意：要求 Node 版本 18+，可使用 [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) 进行本地 Node 版本管理，同时建议使用 [pnpm](https://pnpm.io/zh/installation) 包管理器。\r\n\r\n```shell\r\n# 克隆项目\r\ngit clone https://github.com/yulimchen/vue3-h5-template.git\r\n\r\n# 进入项目目录\r\ncd vue3-h5-template\r\n\r\n# 安装依赖\r\npnpm install\r\n\r\n# 启动服务\r\npnpm dev\r\n```\r\n\r\n[i18n](https://github.com/yulimchen/vue3-h5-template/tree/i18n) 国际化多语言版本 clone 方式\r\n\r\n```shell\r\n# 克隆项目\r\ngit clone -b i18n https://github.com/yulimchen/vue3-h5-template.git\r\n\r\n# 同上进入目录\u0026安装依赖等\r\ncd vue3-h5-template\r\n```\r\n\r\n\r\n如果你需要的是基于 `JavaScript` 构建的 H5 项目模板，可切换到 [js-version](https://github.com/yulimchen/vue3-h5-template/tree/js-version) 分支进行开发\r\n\r\n```shell\r\n# 克隆项目\r\ngit clone -b js-version https://github.com/yulimchen/vue3-h5-template.git\r\n\r\n# 同上进入目录\u0026安装依赖等\r\ncd vue3-h5-template\r\n```\r\n\r\n\r\n\r\n## 文档引导\r\n\r\n\u003e - [按需引入 vant 组件](#vant)\r\n\u003e - [图标使用](#icon)\r\n\u003e - [路由缓存 \u0026 命名注意 ⚠](#router)\r\n\u003e - [调试面板 eruda](#console)\r\n\u003e - [动态设置页面标题](#page-title)\r\n\u003e - [vw 视口适配](#viewport)\r\n\u003e - [Tailwindcss 原子类框架](#tailwindcss)\r\n\u003e - [Git 提交信息规范](#git)\r\n\u003e - [CDN 加载依赖](#CDN)\r\n\r\n\r\n\r\n### \u003cspan id=\"vant\"\u003e按需引入 vant 组件\u003c/span\u003e\r\n\r\n全量引入组件库太过臃肿，项目中使用 `unplugin-vue-components` 插件进行按需自动引入组件，可通过[官方文档](https://vant-ui.github.io/vant/#/zh-CN/quickstart#2.-pei-zhi-cha-jian)了解更多。\r\n\r\n\r\n\r\n### \u003cspan id=\"icon\"\u003e图标使用\u003c/span\u003e\r\n\r\n① **Iconify 图标（推荐）**\r\n\r\nIconify 拥有图标数量超过 20 万的图标库，同时文档比较友好，本项目基于 `Iconify for Vue` 稍微进行了封装。\r\n\r\n使用方法 ⑴：\r\n\r\n![Snipaste_2024-06-27_00-00-17](docs/assets/img/Snipaste_2024-06-27_00-00-17.png)\r\n\r\n基于 Iconify [图标集网站](https://icon-sets.iconify.design/)获取到你想要的图标名称后填入 `i-icon` 组件的 `icon` 属性即可。\r\n\r\n```vue\r\n\u003ci-icon icon=\"fa6-solid:heart\" /\u003e\r\n```\r\n\r\n配合 VS Code [编辑器扩展](https://marketplace.visualstudio.com/items?itemName=antfu.iconify)可在编码时实时预览图标！\r\n\r\n![Snipaste_2024-06-27_00-43-17](docs/assets/img/Snipaste_2024-06-27_00-44-55.png)\r\n\r\n注意，方法 ⑴ 是通过 Iconify API 按需请求获取图标，如果你的项目仅在内网环境部署，可通过👇🏻方法 ⑵ 离线使用图标。\r\n\r\n使用方法 ⑵ ：\r\n\r\n基于 Iconify [图标集网站](https://icon-sets.iconify.design/)搜索到你想要的图标，安装图标对应的图标集依赖包。\r\n\r\n```shell\r\npnpm i -D @iconify-icons/fa6-solid\r\n```\r\n\r\n*依赖包名规则：@iconify-icons/[图标集]*\r\n\r\n![Snipaste_2024-06-27_00-07-10](docs/assets/img/Snipaste_2024-06-27_00-07-10.png)\r\n\r\n引入你想要的图标 data，赋值给 `i-icon` 组件的 `icon` 属性即可。\r\n\r\n*图标路径规则：@iconify-icons/[图标集]/[图标名]*\r\n\r\n```ts\r\nimport Fa6SolidHeart from \"@iconify-icons/fa6-solid/heart\";\r\n```\r\n\r\n```vue\r\n\u003ci-icon :icon=\"Fa6SolidHeart\" /\u003e\r\n```\r\n\r\n案例代码可参考本项目的 `tools` [页面](https://github.com/yulimchen/vue3-h5-template/blob/master/src/views/tools/index.vue)，想对强大的 Iconify 了解更多？请戳 👉 https://iconify.design/docs/\r\n\r\n\r\n\r\n② 本地 SVG 文件图标\r\n\r\n\r\n\u003e 1. 将 svg 图标文件放在 `src/icons/svg` 目录下\r\n\u003e 2. 在项目中直接使用 `\u003csvg-icon name=\"svg图标文件命名\" /\u003e` 即可\r\n\r\n例如：\r\n\r\n本项目 `src/icons/svg` 中放了个叫 `check-in.svg` 的图标文件，然后在组件 `name` 属性中填入文件的命名即可，So easy~\r\n\r\n\r\n```Vue\r\n\u003csvg-icon name=\"check-in\" /\u003e\r\n```\r\n\r\n\u003e 项目中使用了 `unplugin-vue-components` 自动引入组件，所以 `main.ts` 中无需注册全局图标组件。\r\n\r\n\r\n\r\n### \u003cspan id=\"router\"\u003e路由缓存 \u0026 命名注意 ⚠\u003c/span\u003e\r\n\r\n组件默认开启缓存，如某个组件需关闭缓存，在对应路由 `meta` 内的 `noCache` 字段赋值为 `true` 即可。\r\n\r\n```typescript\r\n// src/router/routes.ts\r\nconst routes: Array\u003cRouteRecordRaw\u003e = [\r\n    // ...\r\n    {\r\n        path: \"about\",\r\n        name: \"About\",\r\n        component: () =\u003e import(\"@/views/about/index.vue\"),\r\n        meta: {\r\n            title: \"关于\",\r\n            noCache: true\r\n        }\r\n    }\r\n];\r\n```\r\n\r\n 为了保证页面能被正确缓存，请确保**组件**的 `name` 值和对应路由的 `name` 命名完全相同。\r\n\r\n```vue\r\n\u003c!-- src/views/about/index.vue --\u003e\r\n\u003cscript setup lang=\"ts\"\u003e\r\n// Vue3.3+ defineOptions 宏\r\ndefineOptions({\r\n  name: \"About\"\r\n});\r\n\u003c/script\u003e\r\n\r\n\u003ctemplate\u003e\r\n  \u003cdiv\u003eabout\u003c/div\u003e\r\n\u003c/template\u003e\r\n```\r\n\r\n\r\n\r\n### \u003cspan id=\"console\"\u003e调试面板 eruda\u003c/span\u003e\r\n\r\n![](docs/assets/img/Snipaste_2023-05-04_21-58-28.png)\r\n\r\n为了方便移动端查看 log 信息和调试，开发环境引入了 eruda 调试面板的 cdn。如果你的开发环境不需要的话请在 `.env.development` 中修改值\r\n\r\n```html\r\n# .env.development\r\n\r\n# 开发环境启用 cdn eruda 调试工具。若不启用，将 true 修改为 false 或其他任意值即可\r\nVITE_ENABLE_ERUDA = \"true\"\r\n```\r\n\r\n\r\n\r\n### \u003cspan id=\"page-title\"\u003e动态设置页面标题\u003c/span\u003e\r\n\r\n在路由全局前置守卫中：\r\n\r\n```js\r\n// src/router/index.ts\r\n// ...\r\nrouter.beforeEach((to: toRouteType, from, next) =\u003e {\r\n  // ...\r\n  // 页面 title\r\n  setPageTitle(to.meta.title);\r\n  next();\r\n});\r\n```\r\n\r\n具体实现方法见文件 `src/utils/set-page-title.ts` 。\r\n\r\n\r\n\r\n### \u003cspan id=\"mock\"\u003e开发环境 Mock\u003c/span\u003e\r\n\r\n\u003e 本项目开发环境支持 mock 请求数据，在 `mock` 目录中可配置接口和数据，具体见[文档](https://github.com/pengzhanbo/vite-plugin-mock-dev-server/blob/main/README.zh-CN.md)。\r\n\r\n\r\n\r\n### \u003cspan id=\"viewport\"\u003evw 视口适配\u003c/span\u003e\r\n\r\n使用 `cnjm-postcss-px-to-viewport` 进行视口适配，相关配置见项目根目录下 `postcss.config.js`。\r\n\r\n```js\r\n// postcss.config.js\r\nmodule.exports = {\r\n  plugins: {\r\n    // 使用 cnjm-postcss-px-to-viewport 规避 postcss.plugin was deprecated 警告\r\n    \"cnjm-postcss-px-to-viewport\": {\r\n      viewportWidth: 375, // 根据设计稿设定\r\n      minPixelValue: 1, // 最小的转换数值\r\n      unitPrecision: 2 // 转化精度，转换后保留位数\r\n    },\r\n    autoprefixer: {\r\n      overrideBrowserslist: [\"Android \u003e= 4.0\", \"iOS \u003e= 7\"]\r\n    }\r\n  }\r\n};\r\n```\r\n\r\n\r\n\r\n### \u003cspan id=\"tailwindcss\"\u003eTailwindcss 原子类框架\u003c/span\u003e\r\n\r\nTailwindcss 从 3.0 版本开始默认使用 `JIT` 模式，打包代码不再臃肿，结合 `vite` 使用非常香~ 如果你还没使用过类似的框架，Tailwindcss 首页的[示例](https://tailwindcss.com/)非常直观。\r\n\r\n官方文档：https://tailwindcss.com/docs/padding\r\n\r\n\r\n\r\n### \u003cspan id=\"git\"\u003eGit 提交信息规范\u003c/span\u003e\r\n\r\n项目使用 `husky` 规范 Git 提交信息，遵循社区主流的 [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) 规范。\r\n\r\n```\r\nfeat 增加新功能\r\nfix 修复问题/BUG\r\nstyle 代码风格相关无影响运行结果的\r\nperf 优化/性能提升\r\nrefactor 重构\r\nrevert 撤销修改\r\ntest 测试相关\r\ndocs 文档/注释\r\nchore 依赖更新/脚手架配置修改等\r\nworkflow 工作流改进\r\nci 持续集成\r\ntypes 类型定义文件更改\r\nwip 开发中\r\n```\r\n\r\n```\r\n// 格式\r\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\r\n// 示例\r\nfeat(layout): 布局完成\r\n```\r\n\r\n\r\n\r\n### \u003cspan id=\"CDN\"\u003eCDN 生产环境依赖\u003c/span\u003e\r\n\r\n本模板生产环境默认不开启 CDN 加载依赖，如需开启生产环境加载 CDN 依赖，在根目录生产环境变量文件 `.env.production` 中修改 `VITE_CDN_DEPS` 的值为 `true` 重新打包即可。\r\n\r\n\r\n\r\n## 捐赠\r\n\r\n如果本项目对你有所帮助，可以考虑赞赏一下作者 : D\r\n\r\n\u003cdiv align=\"center\"\u003e\r\n\t\u003cimg src=\"docs/assets/img/donate.png\" alt=\"donate\" style=\"width:50%;\" /\u003e\r\n\u003c/div\u003e\r\n\r\n\r\n\r\n\r\n## 鸣谢\r\n\r\n [vue-element-admin](https://github.com/PanJiaChen/vue-element-admin) \r\n\r\n [vant-demo](https://github.com/youzan/vant-demo) \r\n\r\n [vue-pure-admin](https://github.com/xiaoxian521/vue-pure-admin)\r\n\r\n [vue-vben-admin](https://github.com/vbenjs/vue-vben-admin)\r\n\r\nFont Awesome Solid 图标由 [Dave Gandy](https://github.com/FortAwesome/Font-Awesome) 创作，基于 [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) 许可发布。\r\n\r\n\r\n\r\n## License\r\n\r\n[MIT license](https://github.com/yulimchen/vue3-h5-template/blob/master/LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyulimchen%2Fvue3-h5-template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fyulimchen%2Fvue3-h5-template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fyulimchen%2Fvue3-h5-template/lists"}