From 8ab84371b409cd42e7a1a5e64d7b92f8ce7b2078 Mon Sep 17 00:00:00 2001 From: fonghehe <331002675@qq.com> Date: Thu, 30 Apr 2026 19:19:32 +0800 Subject: [PATCH] docs: update docs --- docs/guide/index.md | 24 ++++++++++--- docs/guide/other/index.md | 12 +++++++ docs/guide/start.md | 16 ++++----- docs/guide/vue2/start.md | 8 +++++ docs/guide/vue3/alias.md | 12 +++++++ docs/guide/vue3/base.md | 22 +++++++++++- docs/guide/vue3/proxy.md | 4 +++ docs/guide/vue3/router.md | 71 ++++++++++++++++++++++++++++++++----- docs/guide/vue3/viewport.md | 25 +++++++++---- docs/index.md | 24 ++++++------- 10 files changed, 178 insertions(+), 40 deletions(-) diff --git a/docs/guide/index.md b/docs/guide/index.md index 4510c81..a16945a 100644 --- a/docs/guide/index.md +++ b/docs/guide/index.md @@ -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 架构版本 | diff --git a/docs/guide/other/index.md b/docs/guide/other/index.md index 7f967f2..515e6a7 100644 --- a/docs/guide/other/index.md +++ b/docs/guide/other/index.md @@ -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 diff --git a/docs/guide/start.md b/docs/guide/start.md index c5cc109..2cdb9ce 100644 --- a/docs/guide/start.md +++ b/docs/guide/start.md @@ -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) diff --git a/docs/guide/vue2/start.md b/docs/guide/vue2/start.md index a0564ea..77170f3 100644 --- a/docs/guide/vue2/start.md +++ b/docs/guide/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 ``` diff --git a/docs/guide/vue3/alias.md b/docs/guide/vue3/alias.md index 1bea6f2..f278000 100644 --- a/docs/guide/vue3/alias.md +++ b/docs/guide/vue3/alias.md @@ -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'; +``` diff --git a/docs/guide/vue3/base.md b/docs/guide/vue3/base.md index 0f35424..bcfc77b 100644 --- a/docs/guide/vue3/base.md +++ b/docs/guide/vue3/base.md @@ -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 = ["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`，避免首次加载组件时出现页面刷新，提升开发体验。 diff --git a/docs/guide/vue3/proxy.md b/docs/guide/vue3/proxy.md index ede077d..eaf6a62 100644 --- a/docs/guide/vue3/proxy.md +++ b/docs/guide/vue3/proxy.md @@ -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` 自动生成代理规则。 diff --git a/docs/guide/vue3/router.md b/docs/guide/vue3/router.md index a4187cf..1489d49 100644 --- a/docs/guide/vue3/router.md +++ b/docs/guide/vue3/router.md @@ -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, +}); +``` diff --git a/docs/guide/vue3/viewport.md b/docs/guide/vue3/viewport.md index 7b82adf..838bfbd 100644 --- a/docs/guide/vue3/viewport.md +++ b/docs/guide/vue3/viewport.md @@ -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; }, + }, }, }; ``` diff --git a/docs/index.md b/docs/index.md index 54a12c8..7b8b99d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -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 部署等开箱即用 ---