# vue-h5-template
**Repository Path**: zhj1214/vue-h5-template
## Basic Information
- **Project Name**: vue-h5-template
- **Description**: h5 => vue + vant
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 2
- **Created**: 2025-03-13
- **Last Updated**: 2025-04-21
## Categories & Tags
**Categories**: Uncategorized
**Tags**: H5, Vue, 框架
## README
# 项目介绍
**🌱 Vue3 全家桶、TS/JS、Vite**
- [x] ⚡ Vue3 + Vite5
- [x] 🍕 TypeScript
- [x] ✨ Vant4 组件库
- [x] 🌀 Tailwindcss 原子类框架
- [x] 👏 集成多种图标方案
- [x] 🍍 Pinia 状态管理
- [x] 🌓 支持深色模式
- [x] 🧀 支持 i18n
- [x] Vue-router 4
- [x] vmin 视口适配
- [x] Axios 封装
- [x] 打包资源 gzip 压缩
- [x] 开发环境支持 Mock 数据
- [x] ESLint
- [x] 首屏加载动画
- [x] 开发环境调试面板
- [x] 生产环境 CDN 依赖
### 环境要求
- Node.js >= 18
- pnpm >= 9
注意：要求 Node 版本 18+，可使用 [nvm](https://github.com/nvm-sh/nvm#installing-and-updating) 进行本地 Node 版本管理，同时建议使用 [pnpm](https://pnpm.io/zh/installation) 包管理器。
### 开发命令
- `pnpm dev`: 启动开发服务器
- `pnpm build`: 构建生产版本
- `pnpm preview`: 本地预览生产构建
- `pnpm lint:eslint`: ESLint 检查并修复
- `pnpm lint:prettier`: Prettier 格式化代码
## 文档引导
> - [按需引入 vant 组件](#vant)
> - [图标使用](#icon)
> - [路由缓存 & 命名注意 ⚠](#router)
> - [调试面板 eruda](#console)
> - [动态设置页面标题](#page-title)
> - [vw 视口适配](#viewport)
> - [Tailwindcss 原子类框架](#tailwindcss)
> - [Git 提交信息规范](#git)
> - [CDN 加载依赖](#CDN)
## 项目结构
```
vue-h5-template/
├── .husky/ # Git 钩子配置
├── .vscode/ # VSCode 编辑器配置
├── build/ # 构建相关配置
│ └── cdn.ts # CDN 配置
├── docs/ # 项目文档
├── mock/ # Mock 数据配置
├── public/ # 公共静态资源
├── scripts/ # 脚本工具
├── src/ # 源代码目录
│ ├── api/ # API 接口定义
│ ├── assets/ # 静态资源文件
│ ├── components/ # 通用组件
│ │ ├── dot-pattern/ # 点状图案组件
│ │ ├── grid-pattern/ # 网格图案组件
│ │ ├── i-icon/ # Iconify 图标组件
│ │ ├── nav-bar/ # 导航栏组件
│ │ ├── svg-icon/ # SVG 图标组件
│ │ └── tabbar/ # 底部标签栏组件
│ ├── composables/ # 组合式 API 函数
│ ├── enums/ # 枚举定义
│ ├── icons/ # 图标文件
│ ├── layout/ # 布局组件
│ ├── locales/ # 国际化文件
│ ├── router/ # 路由配置
│ ├── store/ # Pinia 状态管理
│ ├── styles/ # 样式文件
│ ├── typings/ # TypeScript 类型定义
│ ├── utils/ # 工具函数
│ ├── views/ # 页面视图组件
│ │ ├── about/ # 关于页面
│ │ ├── demo/ # 示例页面
│ │ └── tools/ # 工具页面
│ ├── App.vue # 根组件
│ ├── main.ts # 应用入口文件
│ └── settings.ts # 应用设置
├── .env.development # 开发环境变量
├── .env.production # 生产环境变量
├── .gitignore # Git 忽略文件
├── .nvmrc # Node 版本配置
├── .prettierrc.js # 代码格式化配置
├── .versionrc.json # 版本控制配置
├── commitlint.config.js # 提交信息规范
├── eslint.config.js # ESLint 配置
├── index.html # 入口 HTML
├── package.json # 项目依赖和脚本
├── postcss.config.js # PostCSS 配置
├── tailwind.config.ts # Tailwind 配置
├── tsconfig.json # TypeScript 配置
└── vite.config.ts # Vite 构建配置
```
### 按需引入 vant 组件
全量引入组件库太过臃肿，项目中使用 `unplugin-vue-components` 插件进行按需自动引入组件，可通过[官方文档](https://vant-ui.github.io/vant/#/zh-CN/quickstart#2.-pei-zhi-cha-jian)了解更多。
### 图标使用
① **Iconify 图标（推荐）**
Iconify 拥有图标数量超过 20 万的图标库，同时文档比较友好，本项目基于 `Iconify for Vue` 稍微进行了封装。
使用方法 ⑴：
基于 Iconify [图标集网站](https://icon-sets.iconify.design/)获取到你想要的图标名称后填入 `i-icon` 组件的 `icon` 属性即可。
```vue
```
配合 VS Code [编辑器扩展](https://marketplace.visualstudio.com/items?itemName=antfu.iconify)可在编码时实时预览图标！
注意，方法 ⑴ 是通过 Iconify API 按需请求获取图标，如果你的项目仅在内网环境部署，可通过👇🏻方法 ⑵ 离线使用图标。
使用方法 ⑵ ：
基于 Iconify [图标集网站](https://icon-sets.iconify.design/)搜索到你想要的图标，安装图标对应的图标集依赖包。
```shell
pnpm i -D @iconify-icons/fa6-solid
```
*依赖包名规则：@iconify-icons/[图标集]*
引入你想要的图标 data，赋值给 `i-icon` 组件的 `icon` 属性即可。
*图标路径规则：@iconify-icons/[图标集]/[图标名]*
```ts
import Fa6SolidHeart from "@iconify-icons/fa6-solid/heart";
```
```vue
```
案例代码可参考本项目的 `tools` [页面](https://github.com/yulimchen/vue3-h5-template/blob/master/src/views/tools/index.vue)，想对强大的 Iconify 了解更多？请戳 👉 https://iconify.design/docs/
② 本地 SVG 文件图标
> 1. 将 svg 图标文件放在 `src/icons/svg` 目录下
> 2. 在项目中直接使用 `` 即可
例如：
本项目 `src/icons/svg` 中放了个叫 `check-in.svg` 的图标文件，然后在组件 `name` 属性中填入文件的命名即可，So easy~
```Vue
```
> 项目中使用了 `unplugin-vue-components` 自动引入组件，所以 `main.ts` 中无需注册全局图标组件。
### 路由缓存 & 命名注意 ⚠
组件默认开启缓存，如某个组件需关闭缓存，在对应路由 `meta` 内的 `noCache` 字段赋值为 `true` 即可。
```typescript
// src/router/routes.ts
const routes: Array = [
// ...
{
path: "about",
name: "About",
component: () => import("@/views/about/index.vue"),
meta: {
title: "关于",
noCache: true
}
}
];
```
为了保证页面能被正确缓存，请确保**组件**的 `name` 值和对应路由的 `name` 命名完全相同。
```vue
about
```
### 调试面板 eruda
为了方便移动端查看 log 信息和调试，开发环境引入了 eruda 调试面板的 cdn。如果你的开发环境不需要的话请在 `.env.development` 中修改值
```html
# .env.development
# 开发环境启用 cdn eruda 调试工具。若不启用，将 true 修改为 false 或其他任意值即可
VITE_ENABLE_ERUDA = "true"
```
### 动态设置页面标题
在路由全局前置守卫中：
```js
// src/router/index.ts
// ...
router.beforeEach((to: toRouteType, from, next) => {
// ...
// 页面 title
setPageTitle(to.meta.title);
next();
});
```
具体实现方法见文件 `src/utils/set-page-title.ts` 。
### 开发环境 Mock
> 本项目开发环境支持 mock 请求数据，在 `mock` 目录中可配置接口和数据，具体见[文档](https://github.com/pengzhanbo/vite-plugin-mock-dev-server/blob/main/README.zh-CN.md)。
### vw 视口适配
使用 `cnjm-postcss-px-to-viewport` 进行视口适配，相关配置见项目根目录下 `postcss.config.js`。
```js
// postcss.config.js
module.exports = {
plugins: {
// 使用 cnjm-postcss-px-to-viewport 规避 postcss.plugin was deprecated 警告
"cnjm-postcss-px-to-viewport": {
viewportWidth: 375, // 根据设计稿设定
minPixelValue: 1, // 最小的转换数值
unitPrecision: 2 // 转化精度，转换后保留位数
},
autoprefixer: {
overrideBrowserslist: ["Android >= 4.0", "iOS >= 7"]
}
}
};
```
### Tailwindcss 原子类框架
Tailwindcss 从 3.0 版本开始默认使用 `JIT` 模式，打包代码不再臃肿，结合 `vite` 使用非常香~ 如果你还没使用过类似的框架，Tailwindcss 首页的[示例](https://tailwindcss.com/)非常直观。
官方文档：https://tailwindcss.com/docs/padding
### Git 提交信息规范
项目使用 `husky` 规范 Git 提交信息，遵循社区主流的 [Angular](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-angular) 规范。
```
feat 增加新功能
fix 修复问题/BUG
style 代码风格相关无影响运行结果的
perf 优化/性能提升
refactor 重构
revert 撤销修改
test 测试相关
docs 文档/注释
chore 依赖更新/脚手架配置修改等
workflow 工作流改进
ci 持续集成
types 类型定义文件更改
wip 开发中
```
```
// 格式
():
// 示例
feat(layout): 布局完成
```
### CDN 生产环境依赖
本模板生产环境默认不开启 CDN 加载依赖，如需开启生产环境加载 CDN 依赖，在根目录生产环境变量文件 `.env.production` 中修改 `VITE_CDN_DEPS` 的值为 `true` 重新打包即可。