mirror of
https://github.com/sunniejs/vue-h5-template.git
synced 2026-05-21 10:18:13 +08:00
docs: update docs
This commit is contained in:
fonghehe
parent
5b32fedd9a
commit
8ab84371b4
@ -1,23 +1,39 @@
|
||||
# Vue-H5-Template
|
||||
|
||||
[Vue-H5-Template](https://github.com/sunniejs/vue-h5-template)，是基于 vite7 + vue3.5 + pinia + ( Vant or Varlet or NutUI ) + viewport(VW) 适配方案 ，构建移动端快速开发脚手架
|
||||
[Vue-H5-Template](https://github.com/sunniejs/vue-h5-template)，是基于 Vite 7 + Vue 3.5 + TypeScript 5.9 + Pinia + ( Vant / Varlet / NutUI ) + viewport(VW) 适配方案，构建移动端快速开发脚手架
|
||||
|
||||
## 特点
|
||||
|
||||
### 最新技术栈
|
||||
|
||||
- 框架选型基于当下流行的 vue + vite + ts 模式，精选社区 star 数 和满意度均不错的 ui 框架和 vite 插件，并时常进行更新，确保与官方文档一致
|
||||
- 基于 Vue 3.5 + Vite 7 + TypeScript 5.9，精选社区优质的 UI 框架和 Vite 插件，时常更新，确保与官方文档一致
|
||||
|
||||
### 基于 TypeScript
|
||||
|
||||
- Typescript 逐渐在各种大型的 js 项目中使用，明确的类型定义可以省下不少的开发和维护成本
|
||||
- TypeScript 逐渐在各种大型的 JS 项目中使用，明确的类型定义可以省下不少的开发和维护成本
|
||||
|
||||
### 多 UI 组件库
|
||||
|
||||
- 同时集成 Vant、NutUI、Varlet 三大移动端组件库，按需自动引入，做减法即可
|
||||
|
||||
### 轻量级
|
||||
|
||||
- 不同于集成的脚手架，尽量做到轻量不冗杂，只引入高频次的插件和清晰的示例
|
||||
- 轻装上阵，便于拓展开发，减少学习成本
|
||||
|
||||
### Docker 部署
|
||||
|
||||
- 内置 Dockerfile + Nginx 配置，一键构建部署
|
||||
|
||||
### 通俗易懂的文档
|
||||
|
||||
- 基于最新 VitePress 构建的文档，更快，更便捷
|
||||
- 更快的热更新
|
||||
|
||||
## 其他版本
|
||||
|
||||
| 版本 | 分支 | 说明 |
|
||||
| --- | --- | --- |
|
||||
| Vue 3 + TS | [vue-h5-template](https://github.com/sunniejs/vue-h5-template/tree/vue-h5-template) | 主版本（当前文档） |
|
||||
| Vue 3 + JS | [vue-h5-template-lite](https://github.com/sunniejs/vue-h5-template/tree/vue-h5-template-lite) | 纯 JS 轻量版 |
|
||||
| Vue 2 | [vue2-h5-template](https://github.com/sunniejs/vue-h5-template/tree/vue2-h5-template) | Vue 2 + Vue CLI + Vant 2 |
|
||||
| Monorepo | [fonghehe/vue-h5-template](https://github.com/fonghehe/vue-h5-template) | Monorepo 架构版本 |
|
||||
|
||||
@ -9,3 +9,15 @@
|
||||
### 3、我是一个新手，有什么好的学习建议吗？
|
||||
|
||||
过来人的经验就是熟读文档可以少走很多弯路，很多的人文档没读熟就开始动手，出了问题也不知道如何去解决，墙裂建议先把[文档](https://cn.vuejs.org/)熟读
|
||||
|
||||
### 4、为什么 vue3 版本使用 history 模式而不是 hash？
|
||||
|
||||
Vue 3 版本默认使用 `createWebHistory`（history 模式），URL 更简洁美观。如需 hash 模式，参考[路由文档](/guide/vue3/router.html)切换
|
||||
|
||||
### 5、viewport 适配时 UI 库组件尺寸不对？
|
||||
|
||||
项目已通过 `customFun` 自动处理 Vant / NutUI / Varlet 的 375 设计稿和业务代码 750 设计稿的差异，无需手动处理
|
||||
|
||||
### 6、如何部署到生产环境？
|
||||
|
||||
项目内置了 `Dockerfile` + `nginx.conf`，可直接使用 Docker 部署。如使用 history 模式，确保服务端已配置 fallback
|
||||
|
||||
@ -2,16 +2,16 @@
|
||||
|
||||
## Node 版本要求
|
||||
|
||||
推荐 Node.js 20.10.0+ 以上的版本，你可以使用 [nvm](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 在同一台电脑上管理多个 Node 版本。
|
||||
| 模版 | Node.js | 包管理器 |
|
||||
| --- | --- | --- |
|
||||
| vue3-template | >= 20.10.0 | pnpm >= 9.12.0 |
|
||||
| vue2-template | >= 14（推荐 16+） | yarn 或 npm |
|
||||
|
||||
## 包管理器
|
||||
|
||||
推荐使用 pnpm（>= 9.12.0），本项目仅保证在 pnpm 下正确运行。
|
||||
你可以使用 [nvm](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 在同一台电脑上管理多个 Node 版本。
|
||||
|
||||
## 启动项目
|
||||
|
||||
项目中包含 vue2 和 vue3 两套模版
|
||||
项目中包含 vue2 和 vue3 两套模版：
|
||||
|
||||
如你使用的是 vue2-template，请参考[vue2 项目启动](./vue2/start.md)
|
||||
|
||||
如你使用的是 vue3-template，请参考[vue3 项目启动](./vue3/start.md)
|
||||
- vue3-template：请参考 [vue3 项目启动](./vue3/start.md)
|
||||
- vue2-template：请参考 [vue2 项目启动](./vue2/start.md)
|
||||
|
||||
@ -1,5 +1,10 @@
|
||||
# 启动项目
|
||||
|
||||
## 环境要求
|
||||
|
||||
- Node.js >= 14（推荐 16+）
|
||||
- yarn（推荐）或 npm
|
||||
|
||||
```bash
|
||||
# 拉取项目
|
||||
git clone https://github.com/sunniejs/vue-h5-template
|
||||
@ -12,4 +17,7 @@ yarn install
|
||||
|
||||
# 启动项目
|
||||
yarn serve
|
||||
|
||||
# 打包
|
||||
yarn build
|
||||
```
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# alias
|
||||
|
||||
项目在 `vite.config.mts` 中配置了路径别名，方便引用 `src` 和 `types` 目录下的文件：
|
||||
|
||||
```javascript
|
||||
import { fileURLToPath, URL } from 'node:url';
|
||||
|
||||
@ -10,3 +12,13 @@ resolve: {
|
||||
},
|
||||
},
|
||||
```
|
||||
|
||||
使用示例：
|
||||
|
||||
```typescript
|
||||
// 引用 src 下的文件
|
||||
import { http } from '@/utils/request';
|
||||
|
||||
// 引用 types 下的类型
|
||||
import type { UserInfo } from '#/index';
|
||||
```
|
||||
|
||||
@ -12,6 +12,8 @@ base: './',
|
||||
base: '/app/',
|
||||
```
|
||||
|
||||
完整配置：
|
||||
|
||||
```javascript
|
||||
export default function ({ command, mode }: ConfigEnv): UserConfig {
|
||||
const isProduction = command === "build";
|
||||
@ -19,6 +21,17 @@ export default function ({ command, mode }: ConfigEnv): UserConfig {
|
||||
const env = loadEnv(mode, root);
|
||||
const viteEnv = wrapperEnv(env);
|
||||
|
||||
const devOptimizeDepsInclude: Array<string> = ["eruda"];
|
||||
// 开发环境自动扫描 UI 库组件目录，优化依赖预构建
|
||||
if (!isProduction) {
|
||||
const uiLibraries = [
|
||||
{ name: "vant/es", path: "node_modules/vant/es" },
|
||||
{ name: "@nutui/nutui/dist/packages", path: "node_modules/@nutui/nutui/dist/packages" },
|
||||
{ name: "@varlet/ui/es", path: "node_modules/@varlet/ui/es" },
|
||||
];
|
||||
// ...自动将组件样式加入 optimizeDeps.include
|
||||
}
|
||||
|
||||
return {
|
||||
base: "/",
|
||||
root,
|
||||
@ -37,7 +50,7 @@ export default function ({ command, mode }: ConfigEnv): UserConfig {
|
||||
minify: "terser",
|
||||
terserOptions: {
|
||||
compress: {
|
||||
//生产环境时移除console
|
||||
// 生产环境时移除 console
|
||||
drop_console: true,
|
||||
drop_debugger: true,
|
||||
},
|
||||
@ -52,6 +65,13 @@ export default function ({ command, mode }: ConfigEnv): UserConfig {
|
||||
},
|
||||
},
|
||||
},
|
||||
optimizeDeps: {
|
||||
include: [...devOptimizeDepsInclude],
|
||||
},
|
||||
};
|
||||
}
|
||||
```
|
||||
|
||||
## optimizeDeps 说明
|
||||
|
||||
项目在开发环境下会自动扫描 Vant、NutUI、Varlet 组件目录，将组件样式文件加入 `optimizeDeps.include`，避免首次加载组件时出现页面刷新，提升开发体验。
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# proxy 跨域
|
||||
|
||||
在 `vite.config.mts` 的 `server.proxy` 中配置代理，解决开发环境跨域问题：
|
||||
|
||||
```javascript
|
||||
server: {
|
||||
proxy: {
|
||||
@ -11,3 +13,5 @@ server: {
|
||||
}
|
||||
},
|
||||
```
|
||||
|
||||
项目同时在 `build/vite/proxy.ts` 中提供了基于环境变量的代理配置封装，可根据 `.env.*` 中的 `VITE_URL_PREFIX` 自动生成代理规则。
|
||||
|
||||
@ -1,11 +1,15 @@
|
||||
# vue-router
|
||||
|
||||
本案例采用 `hash` 模式，开发者根据需求修改 `mode` `base`
|
||||
本案例采用 `history` 模式，开发者可根据需求切换为 `hash` 模式
|
||||
|
||||
**注意**：如果你使用了 `history` 模式， `vite.config.mts` 中的 `base` 要做对应的**修改**
|
||||
**注意**：如果你使用了 `history` 模式，`vite.config.mts` 中的 `base` 要做对应的**修改**，部署时也需要服务端（如 Nginx）配置 fallback
|
||||
|
||||
前往: [vite.config.mts 基础配置](/guide/vue3/base)
|
||||
|
||||
## 路由配置
|
||||
|
||||
`src/router/routes.ts`：
|
||||
|
||||
```typescript
|
||||
import type { RouteRecordRaw } from "vue-router";
|
||||
|
||||
@ -23,7 +27,39 @@ export const routes: RouteRecordRaw[] = [
|
||||
keepAlive: true,
|
||||
},
|
||||
},
|
||||
// ... 其他子路由
|
||||
{
|
||||
path: "list",
|
||||
component: () => import("@/views/list/index.vue"),
|
||||
meta: {
|
||||
title: "common.tabbar.list",
|
||||
keepAlive: true,
|
||||
},
|
||||
},
|
||||
{
|
||||
path: "member",
|
||||
component: () => import("@/views/member/index.vue"),
|
||||
meta: {
|
||||
title: "common.tabbar.member",
|
||||
keepAlive: true,
|
||||
},
|
||||
},
|
||||
{
|
||||
path: "demo",
|
||||
component: () => import("@/views/demo/index.vue"),
|
||||
meta: {
|
||||
title: "common.tabbar.demo",
|
||||
keepAlive: true,
|
||||
},
|
||||
},
|
||||
{
|
||||
name: "listDetails",
|
||||
path: "/details",
|
||||
component: () => import("@/views/list/details/index.vue"),
|
||||
meta: {
|
||||
title: "common.list.details",
|
||||
border: false,
|
||||
},
|
||||
},
|
||||
],
|
||||
},
|
||||
{
|
||||
@ -43,17 +79,36 @@ export const routes: RouteRecordRaw[] = [
|
||||
];
|
||||
```
|
||||
|
||||
路由实例创建：
|
||||
## 路由实例
|
||||
|
||||
`src/router/index.ts`：
|
||||
|
||||
```typescript
|
||||
import { createRouter, createWebHashHistory } from "vue-router";
|
||||
import { createRouter, createWebHistory } from "vue-router";
|
||||
import type { Router } from "vue-router";
|
||||
import routes from "./routes";
|
||||
|
||||
const router = createRouter({
|
||||
history: createWebHashHistory(),
|
||||
const router: Router = createRouter({
|
||||
history: createWebHistory(import.meta.env.BASE_URL),
|
||||
routes,
|
||||
scrollBehavior: () => ({ left: 0, top: 0 }),
|
||||
});
|
||||
|
||||
router.beforeEach(async (_to, _from, next) => {
|
||||
next();
|
||||
});
|
||||
|
||||
export default router;
|
||||
```
|
||||
|
||||
## 切换为 hash 模式
|
||||
|
||||
如需使用 hash 模式，只需修改 `src/router/index.ts`：
|
||||
|
||||
```typescript
|
||||
import { createRouter, createWebHashHistory } from "vue-router";
|
||||
|
||||
const router = createRouter({
|
||||
history: createWebHashHistory(),
|
||||
routes,
|
||||
});
|
||||
```
|
||||
|
||||
@ -10,26 +10,37 @@
|
||||
|
||||
```javascript
|
||||
// https://github.com/michael-ciniawsky/postcss-load-config
|
||||
const path = require("path");
|
||||
|
||||
const judgeComponent = (file) => {
|
||||
const ignore = ["vant", "@nutui", "@varlet"];
|
||||
return ignore.some((item) => path.join(file).includes(path.join("node_modules", item)));
|
||||
};
|
||||
|
||||
module.exports = {
|
||||
plugins: {
|
||||
autoprefixer: { overrideBrowserslist: ['Android 4.1', 'iOS 7.1', 'Chrome > 31', 'ff > 31', 'ie >= 8'] },
|
||||
'cnjm-postcss-px-to-viewport': {
|
||||
unitToConvert: 'px', // 要转化的单位
|
||||
autoprefixer: { overrideBrowserslist: ["Android 4.1", "iOS 7.1", "Chrome > 31", "ff > 31", "ie >= 8"] },
|
||||
"cnjm-postcss-px-to-viewport": {
|
||||
unitToConvert: "px", // 要转化的单位
|
||||
viewportWidth: 750, // UI设计稿的宽度
|
||||
unitPrecision: 6, // 转换后的精度，即小数点位数
|
||||
propList: ['*'], // 指定转换的css属性的单位，*代表全部css属性的单位都进行转换
|
||||
viewportUnit: 'vw', // 指定需要转换成的视窗单位，默认vw
|
||||
fontViewportUnit: 'vw', // 指定字体需要转换成的视窗单位，默认vw
|
||||
propList: ["*"], // 指定转换的css属性的单位，*代表全部css属性的单位都进行转换
|
||||
viewportUnit: "vw", // 指定需要转换成的视窗单位，默认vw
|
||||
fontViewportUnit: "vw", // 指定字体需要转换成的视窗单位，默认vw
|
||||
minPixelValue: 1, // 默认值1，小于或等于1px则不进行转换
|
||||
mediaQuery: true, // 是否在媒体查询的css代码中也进行转换，默认false
|
||||
replace: true, // 是否转换后直接更换属性值
|
||||
landscape: false, // 是否添加根据 landscapeWidth 生成的媒体查询条件
|
||||
landscapeUnit: "rem", // 横屏时使用的单位
|
||||
landscapeWidth: 1134, // 横屏时使用的视口宽度
|
||||
include: [],
|
||||
exclude: [], // 设置忽略文件，用正则做目录名匹配
|
||||
customFun: ({ file }) => {
|
||||
// 这个自定义的方法是针对处理vant组件下的设计稿为375问题
|
||||
// 这个自定义的方法是针对处理vant/nutui/varlet组件下的设计稿为375问题
|
||||
const designWidth = judgeComponent(file) ? 375 : 750;
|
||||
return designWidth;
|
||||
},
|
||||
},
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
@ -2,11 +2,11 @@
|
||||
layout: home
|
||||
|
||||
title: Vue-H5-Template
|
||||
titleTemplate: 一个快速开发的vue h5移动端脚手架
|
||||
titleTemplate: 一个快速开发的 Vue H5 移动端脚手架
|
||||
|
||||
hero:
|
||||
name: Vue-H5-Template
|
||||
text: 一个快速开发的Vue H5移动端脚手架
|
||||
text: 一个快速开发的 Vue H5 移动端脚手架
|
||||
image:
|
||||
src: https://cdn.jsdelivr.net/gh/fonghehe/picture/vue-h5-template/logo.png
|
||||
alt: sunnie
|
||||
@ -15,20 +15,20 @@ hero:
|
||||
text: 开始
|
||||
link: /guide/
|
||||
- theme: alt
|
||||
text: Github仓库
|
||||
text: Github 仓库
|
||||
link: https://github.com/sunniejs/vue-h5-template
|
||||
|
||||
features:
|
||||
- icon: 💡
|
||||
title: 开箱即用
|
||||
details: 集成vue2、vue3的移动端快速开发模版，学习成本低，易上手
|
||||
- icon: 🚀
|
||||
title: 最新技术栈
|
||||
details: Vue 3.5 + Vite 7 + TypeScript 5.9 + Pinia，保持与官方同步更新
|
||||
- icon: 📱
|
||||
title: 多 UI 组件库
|
||||
details: 同时集成 Vant、NutUI、Varlet 三大移动端组件库，按需自动引入
|
||||
- icon: 📦
|
||||
title: 代码规范
|
||||
details: 完整的eslint、prettier、stylelint规范，加上husky，帮助你更好的管理代码
|
||||
details: ESLint flat config + Prettier + Stylelint + Husky + lint-staged 全链路规范
|
||||
- icon: 🛠️
|
||||
title: 配置优化
|
||||
details: 完整配置的vue脚手架插件和优化，让你专注于业务开发，更高效
|
||||
- icon: ⚙️
|
||||
title: More
|
||||
details: 加入我们，更多能力等你挖掘....
|
||||
title: 丰富插件
|
||||
details: Mock、Eruda 调试、PWA、图片压缩、gzip、多语言、Docker 部署等开箱即用
|
||||
---
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user