README.md



H5 Vite Template

基于 Vue 3 + Vite + Vant 4 的移动端 H5 项目模板


特性


⚡️ Vite - 极速的开发体验
🖖 Vue 3 - 渐进式 JavaScript 框架
📱 Vant 4 - 轻量、可靠的移动端组件库
🎨 Tailwind CSS - 原子化 CSS 框架
📦 Pinia - 符合直觉的 Vue.js 状态管理库
🛣️ Vue Router - Vue.js 官方路由
📡 Axios - 基于 Promise 的 HTTP 客户端
🔧 ESLint - 代码质量检查
📐 PostCSS - CSS 后处理器
📱 移动端适配 - 基于 postcss-px-to-viewport 的移动端适配方案


目录结构

h5_vite_template/
├── public/                 # 静态资源
├── src/
│   ├── api/               # API 接口
│   ├── assets/            # 资源文件
│   ├── components/        # 通用组件
│   ├── router/            # 路由配置
│   ├── stores/            # 状态管理
│   ├── utils/             # 工具函数
│   ├── views/             # 页面组件
│   ├── App.vue            # 根组件
│   ├── main.js            # 入口文件
│   └── style.css          # 全局样式
├── .env                   # 环境变量
├── .env.development       # 开发环境变量
├── .env.production        # 生产环境变量
├── .gitignore             # Git 忽略文件
├── index.html             # HTML 模板
├── package.json           # 项目配置
├── postcss.config.js      # PostCSS 配置
├── tailwind.config.js     # Tailwind CSS 配置
└── vite.config.js         # Vite 配置


快速开始


安装依赖

npm install
# 或
yarn install
# 或
pnpm install


开发

npm run dev
# 或
yarn dev
# 或
pnpm dev


构建

npm run build
# 或
yarn build
# 或
pnpm build


预览

npm run preview
# 或
yarn preview
# 或
pnpm preview


配置说明


环境变量

项目支持多环境配置，通过 .env 文件进行管理：


.env - 所有环境的默认配置

.env.development - 开发环境配置

.env.production - 生产环境配置


移动端适配

项目使用 postcss-px-to-viewport 进行移动端适配，设计稿基准为 375px。


路由配置

路由配置位于 src/router/index.js，支持：


路由懒加载
路由守卫
页面标题设置
滚动行为控制


状态管理

使用 Pinia 进行状态管理，store 文件位于 src/stores/ 目录。


API 请求

API 请求基于 Axios 封装，配置文件位于 src/utils/request.js，支持：


请求/响应拦截器
自动 Loading
错误处理
Token 自动携带


全局加载机制（低网速优化）


在 src/stores/loading.js 新增 Pinia 全局 loading store，使用并发计数管理加载状态。
在 src/utils/axios.js 请求/响应拦截器接入该 store：请求开始计数 +1、响应成功计数 -1、任一错误发生时重置计数并关闭加载。
在 src/App.vue 添加全屏蒙版与 van-loading 组件，居中展示“加载中...”动画，直至页面所有接口完成或出现错误。
行为说明：


并发多个接口时仅在全部完成后关闭蒙版；
任一接口失败立即关闭蒙版，错误提示交由业务层处理（如 api/fn.js 中的 showFailToast）。


相关文件


src/stores/loading.js：全局 loading 状态管理。

src/utils/axios.js：拦截器计数与异常兜底。

src/App.vue：全屏 loading 蒙版展示。


优化建议


如需对某些非页面关键接口（如埋点、心跳）排除 loading，可在拦截器中根据 config.url 做白名单过滤。


组件说明


页面组件


Home - 首页，展示轮播图、菜单网格、通知栏等

About - 关于页面，展示项目信息和功能特性

Profile - 个人中心，展示用户信息和功能菜单

Demo - 组件演示页面，展示 Vant 组件使用示例

NotFound - 404 页面


通用组件


LoadingSpinner - 加载动画组件

EmptyState - 空状态组件


登录模块（Mock）


页面：src/views/Login.vue

功能：手机号 + 验证码登录；发送验证码含 60 秒倒计时；登录成功写入 Pinia 并跳转首页。
接口：


send_sms_mock(phone)：发送验证码，模拟成功返回（约 500ms）。

login_mock(phone, code)：验证码登录，返回 token 和 userInfo（约 600ms）。


说明：暂不加样式，待设计稿出具后统一视觉优化。


访问控制（登录态）


入口逻辑：首页“照片查询和下载”入口点击时将根据登录态跳转。


未登录：跳转 #/login

已登录：跳转 #/studentInfo


路由守卫：对 #/studentInfo 做登录校验，未登录访问将被重定向到登录页并附带原始目标路径，登录后可返回。


开发规范


代码风格

项目使用 ESLint 进行代码质量检查，请遵循以下规范：


使用 2 空格缩进
使用单引号
行末不加分号
组件名使用 PascalCase
文件名使用 kebab-case


Git 提交规范

建议使用以下格式进行 Git 提交：

<type>(<scope>): <subject>

<body>

<footer>


类型说明：


feat: 新功能

fix: 修复 bug

docs: 文档更新

style: 代码格式调整

refactor: 代码重构

test: 测试相关

chore: 构建过程或辅助工具的变动


部署


构建产物

执行 npm run build 后，构建产物将输出到 dist 目录。


静态部署

构建产物可以部署到任何静态文件服务器，如：


Nginx
Apache
Vercel
Netlify
GitHub Pages


自动部署脚本


在 scripts/deploy.sh 提供一键部署脚本，串行执行：


构建项目：npm run build

上传静态资源到七牛云：qshell qupload ~/.qshell/upload.conf

打包并上传到服务器：打包 stdj，通过 scp -P 12101 上传到 zhsy@oa.jcedu.org:/home/www/f，远端解压后删除压缩包


使用方法：


先确保本机安装 qshell 且 ~/.qshell/upload.conf 已正确配置
运行：bash scripts/deploy.sh

可根据需要在脚本内调整服务器地址、端口与远端目录


注意事项


如果部署到子路径，需要在 vite.config.js 中配置 base 选项
确保服务器支持 History 模式的路由
生产环境需要配置正确的 API 地址


浏览器支持


Chrome >= 87
Firefox >= 78
Safari >= 14
iOS Safari >= 14.4
Android Browser >= 87


许可证

MIT License