开箱即用的 Vue3 移动端 H5 项目基础模板

方案简介

vue3-h5-template 是一个基于 Vue3 全家桶、TypeScript/JavaScript、Vite 构建工具的开箱即用移动端项目基础模板。它集成了 Vant4 组件库、Tailwindcss 原子类框架、Pinia 状态管理、Vue-router 4 等主流技术栈，并内置 vmin 视口适配、Axios 封装、Mock 数据、深色模式、首屏加载动画等移动端常用能力。适合需要快速启动移动端 H5 项目开发的团队与个人开发者，免去从零搭建脚手架的成本。

实施步骤

1. 克隆项目

shell
git clone https://github.com/yulimchen/vue3-h5-template.git

2. 进入项目目录并安装依赖

shell
cd vue3-h5-template
pnpm install

3. 启动服务

shell
pnpm dev

如需 i18n 国际化多语言版本：

shell
git clone -b i18n https://github.com/yulimchen/vue3-h5-template.git

如需 JavaScript 版本：

shell
git clone -b js-version https://github.com/yulimchen/vue3-h5-template.git

使用与配置要点

• 按需引入 Vant 组件：使用 unplugin-vue-components 插件进行按需自动引入组件
• 图标使用：推荐 Iconify 图标（超过 20 万图标），；内网环境可安装图标集依赖包离线使用；本地 SVG 放在 src/icons/svg 目录后用
• 路由缓存：组件默认开启缓存，需关闭时在路由 meta.noCache 赋值 true；请确保组件 name 与路由 name 完全相同
• 调试面板：开发环境动态加载 eruda，可通过 .env.development 中 VITE_ENABLE_ERUDA 开关
• 页面标题：在路由全局前置守卫中通过 setPageTitle(to.meta.title) 设置
• Mock 数据：在 mock 目录中配置接口和数据
• 视口适配：使用 cnjm-postcss-px-to-viewport，配置见 postcss.config.js（viewportWidth: 375）
• 生产环境 CDN：在 .env.production 中将 VITE_CDN_DEPS 改为 true 重新打包

注意事项与常见问题

• 如某个组件需关闭缓存，在对应路由 meta 内的 noCache 字段赋值为 true
• 为了保证页面能被正确缓存，请确保组件的 name 值和对应路由的 name 命名完全相同
• Iconify 方法⑴ 通过 API 按需请求图标，仅在内网环境部署时使用离线图标集依赖包
• 开发环境调试面板若不需要，在 .env.development 中将 VITE_ENABLE_ERUDA 的 true 修改为 false

优缺点

• ✓ 开箱即用，功能齐全
• ✓ 支持 TS/JS 双版本分支
• ✕ 要求 Node 版本 20+

出处

本方案挖掘自开源项目 yulimchen/vue3-h5-template，方案内容与实施命令均来自其 README 原文。