docs: update docs

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 架构版本 |

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

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 |
 
-## 包管理器
+你可以使用 [nvm](https://github.com/nvm-sh/nvm) 或 [nvm-windows](https://github.com/coreybutler/nvm-windows) 在同一台电脑上管理多个 Node 版本。
-
-推荐使用 pnpm（>= 9.12.0），本项目仅保证在 pnpm 下正确运行。
 
 ## 启动项目
 
-项目中包含 vue2 和 vue3 两套模版
+项目中包含 vue2 和 vue3 两套模版：
 
-如你使用的是 vue2-template，请参考[vue2 项目启动](./vue2/start.md)
+- vue3-template：请参考 [vue3 项目启动](./vue3/start.md)
-
+- vue2-template：请参考 [vue2 项目启动](./vue2/start.md)
-如你使用的是 vue3-template，请参考[vue3 项目启动](./vue3/start.md)

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
 ```

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';
+```

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<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`，避免首次加载组件时出现页面刷新，提升开发体验。

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` 自动生成代理规则。

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({
+const router: Router = createRouter({
-  history: createWebHashHistory(),
+  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,
+});
+```

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'] },
+    autoprefixer: { overrideBrowserslist: ["Android 4.1", "iOS 7.1", "Chrome > 31", "ff > 31", "ie >= 8"] },
-    'cnjm-postcss-px-to-viewport': {
+    "cnjm-postcss-px-to-viewport": {
-      unitToConvert: 'px', // 要转化的单位
+      unitToConvert: "px", // 要转化的单位
       viewportWidth: 750, // UI设计稿的宽度
       unitPrecision: 6, // 转换后的精度，即小数点位数
-      propList: ['*'], // 指定转换的css属性的单位，*代表全部css属性的单位都进行转换
+      propList: ["*"], // 指定转换的css属性的单位，*代表全部css属性的单位都进行转换
-      viewportUnit: 'vw', // 指定需要转换成的视窗单位，默认vw
+      viewportUnit: "vw", // 指定需要转换成的视窗单位，默认vw
-      fontViewportUnit: '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;
       },
+    },
   },
 };
 ```

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: 💡
+  - icon: 🚀
-    title: 开箱即用
+    title: 最新技术栈
-    details: 集成vue2、vue3的移动端快速开发模版，学习成本低，易上手
+    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: 配置优化
+    title: 丰富插件
-    details: 完整配置的vue脚手架插件和优化，让你专注于业务开发，更高效
+    details: Mock、Eruda 调试、PWA、图片压缩、gzip、多语言、Docker 部署等开箱即用
-  - icon: ⚙️
-    title: More
-    details: 加入我们，更多能力等你挖掘....
 ---