# vite-vue3-h5

**Repository Path**: yuyingqianduan/vite-vue3-h5

## Basic Information

- **Project Name**: vite-vue3-h5
- **Description**: vue3+vite5+ts+pinia通用h5移动端项目架子
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 9
- **Forks**: 4
- **Created**: 2024-08-31
- **Last Updated**: 2025-04-12

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# vite-vue3-h5

- [vue](https://cn.vuejs.org/)
- [prettier](https://www.prettier.cn/)
- [eslint](https://eslint.nodejs.cn/)
- [Stylelint](https://stylelint.nodejs.cn/)
- [vite](https://cn.vitejs.dev/)
- [typescript](https://www.typescriptlang.org/)
- [vant](https://vant.pro/vant/#/zh-CN)
- [pinia](https://pinia.vuejs.org/)

## 介绍

使用 `pnpm create vite` 名称创建的项目
vue3 + vite5 + ts + pinia 通用 h5 移动端项目架子，包含 vue3 + vite5 + ts + pinia + vant4 等技术栈，采用全新（当前日期最新版本）技术 包括 eslint v9版本、vue3.4、vite5、vant4、typescript5.x、prettier 3.x、stylelint 16版本、pinia 2.0版本等等，适合快速搭建移动端项目，提升开发效率

## 安装教程

1.  pnpm intall 安装依赖包
2.  pnpm run dev 启动项目
3.  pnpm run build 打包项目

## eslint 安装

执行下面命令自动初始化配置文件 根目录自动生成（没有的需要手动创建 执行`shell`命令`npx eslint --init`） `eslint.config.js` 文件，无需根目录创建 `.eslintignore` 文件

### rule 配置规则

官方原话 `Node.js < v18.18、v19` 不再支持，使用 `ESLint v9.0.0` 时，请确保至少升级到 `Node.js v18.18.0`。需要仔细检查的一件重要事情是通过编辑器集成使用 `ESLint` 时编辑器支持的 `Node.js` 版本。如果你无法升级，我们建议你继续使用 `ESLint v8.56.0`，直到你能够升级 `Node.js`

- "off" 或 0 - 关闭规则
- "warn" 或 1 - 打开规则作为警告（不影响退出代码）
- "error" 或 2 - 打开规则作为错误（触发时退出代码为 1）

```shell
npm init @eslint/config@latest
```

## prettier 安装

执行下面命令自动初始化配置文件 根目录创建 `.prettierrc.mjs` 文件，并且根目录创建 `.prettierignore` 文件

```shell
pnpm i prettier -D
```

## Stylelint 安装

根目录创建 `stylelint.config.mjs` 写入配置文件即可，根目录创建 `.stylelintignore` 文件

```shell
pnpm add  postcss-less postcss-html stylelint-config-recommended-less stylelint-config-standard stylelint-config-standard-vue stylelint-less stylelint-order -D
```

::: tip
`stylelint-config-prettier` 用于禁用 `stylelint` 与 `prettier` 冲突的规则，避免 `stylelint` 与 `prettier` 相互影响，避免不必要的错误，但是 [stylelint v15版本开始就废除了该插件说明](https://stylelint.nodejs.cn/migration-guide/to-15)该插件已经不再需要了，所以不需要安装了
:::

## browserslist 配置文件

根目录创建 `.browserslistrc` 文件，配置浏览器兼容性，具体配置参考 [browserslist](https://github.com/browserslist/browserslist)

```shell
# 安装 browserslist 依赖
npm install --save-dev browserslist
# 验证你的配置是否正确
npx browserslist
```

## 代码提交检查 Husky + Lint-staged + Commitlint + Commitizen + cz-git

1. Husky + Lint-staged

```shell
pnpm add husky lint-staged -D

## 初始化后会生成 .husky文件 自动生成脚本 package.json 的 scripts 中 prepare": "husky
npx husky init
```

2. 配置 lint-staged 脚本，在 package.json 中添加 scripts 脚本

```shell
#  修改 .husky文件中的 pre-commit 脚本 配置
npm run lint:lint-staged
```

3. 配置 Commitlint + Commitizen + cz-git

Commitlint 检查您的提交消息是否符合 Conventional commit format

```shell
pnpm add @commitlint/config-conventional @commitlint/cli -D

pnpm add commitizen cz-git -D
# 添加 钩子 commit-msg 可执行下面命令也可手动添加 并配置 npx --no -- commitlint --edit $1
node --eval "fs.writeFileSync('.husky/commit-msg','')"
```

```json
// package.json
  "scripts": {
    "lint:lint-staged": "lint-staged"
  },
 "husky": {
    "hooks": {
      "pre-commit": "lint-staged"
    }
  },
  // 自由配置
  "lint-staged": {
    "*.{js,ts,vue}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{cjs,json}": [
      "prettier --write"
    ],
    "*.{vue,html}": [
      "eslint --fix",
      "prettier --write",
      "stylelint --fix"
    ],
    // 当你运行 stylelint 时，通常它会预期至少一个文件被处理。如果没有文件匹配到，或者文件内容为空，stylelint 可能会抛出一个错误，以提示没有输入需要检查
    // 使用 --allow-empty-input 可以避免这种情况。如果输入为空或者没有匹配的文件，它不会抛出错误，而是正常结束
    "*.{less,css}": [
      "stylelint --fix --allow-empty-input",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
```

## 安装vant UI 库

```shell
pnpm add vant

# 可选安装 如有需要再安装 我没安装
pnpm add @vant/use
```

## 按需引入vant组件

```ts
import { defineConfig } from 'vite';
import vue from '@vitejs/plugin-vue';
// vant 按需引入配置
import AutoImport from 'unplugin-auto-import/vite';
import Components from 'unplugin-vue-components/vite';
import { VantResolver } from '@vant/auto-import-resolver';

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [
    vue(),
    AutoImport({
      resolvers: [VantResolver()],
      // 安装两行后你会发现在组件中不用再导入ref，reactive等
      imports: ['vue', 'vue-router'],
      // 存放的位置
      dts: 'src/typings/auto-import.d.ts'
    }),
    Components({
      resolvers: [VantResolver()],
      // 存放的位置: 引入组件的,包括自定义组件
      dts: 'src/typings/components.d.ts'
    })
  ]
});
```

### 按需引入组件样式

```shell
pnpm add @vant/auto-import-resolver unplugin-vue-components unplugin-auto-import -D
```

### 底部安全区适配

```html
<!-- 在 head 标签中添加 meta 标签，并设置 viewport-fit=cover 值 -->
<meta
  name="viewport"
  content="width=device-width, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0, viewport-fit=cover"
/>

<!-- 开启顶部安全区适配 -->
<van-nav-bar safe-area-inset-top />

<!-- 开启底部安全区适配 -->
<van-number-keyboard safe-area-inset-bottom />
```

::: tip

- `Rsbuild` 是基于 `Rspack` 的构建工具，由 `Vant` 作者开发，具备一流的构建速度和开发体验，对 `Vant` 提供第一优先级支持
- 免费 `CDN` 一般用于制作原型或个人小型项目，不推荐在企业生产环境中使用免费 `CDN`
- `Vant` 默认支持 `Tree Shaking`，因此你不需要配置任何插件，通过 `Tree Shaking` 即可移除不需要的 `JS` 代码，但 `CSS` 样式无法通过这种方式优化
- 在 `<script setup>` 中可以直接使用 `Vant` 组件，不需要进行组件注册
- 在 `JSX` 和 `TSX` 中可以直接使用 `Vant` 组件，不需要进行组件注册
- `iPhone X` 等机型底部存在底部指示条，指示条的操作区域与页面底部存在重合，容易导致用户误操作，因此我们需要针对这些机型进行安全区适配
- `Vant` 所有组件都是基于 `Vue` 框架实现的，没有针对 `uni-app` 进行适配，因此不保证各个组件在 `uni-app` 下的可用性
  :::

## 安装less预处理器

因为vant组件库的样式文件是less文件，所以选择less预处理器方便主题定制

```shell
# 只需要安装less即可 vite内置了常用的预处理器支持 less-loader 这样的无需安装即可使用
pnpm add less -D
```

## 移动端适配机型

一般移动端适配，使用 rem布局 或 Viewport (vw/vh)，这里我们选择 vw/vh 布局，这样可以根据屏幕大小自适应，适配更多机型 现代手机都支持这些布局方式了（都vue3了该摈弃的就摈弃吧）

这里咱们借助 `postcss-px-to-viewport-8-plugin` 该插件可以将px单位转换为vw单位（自动转换为vw单位），以达到移动端适配的目的

```shell
# postcss-px-to-viewport 不适配postcss 8.0+ 最新版本的, 已弃用，目前有基于 postcss 8 8.0+的插件：postcss-px-to-viewport-8-plugin
pnpm add postcss autoprefixer postcss-px-to-viewport-8-plugin -D
```

::: tip

- 虽然`postcss-px-to-viewport-8-plugin`做适配，但是行内样式不能转换为`vw`，需要额外做处理
- 自定义写个vite插件处理行内样式 or 不做处理 尽量不写行内样式便于统一维护css代码是合理之道
  :::

## 安装 pinia & pinia 数据持久化

安装 pinia 并且配置 pinia 和 pinia 数据持久化，在src下新建 store 文件夹

```shell
# 安装 pinia
pnpm add pinia

# 安装 pinia 数据持久化插件 （官方推荐插件）
pnpm add pinia-plugin-persist
```

## nprogress 进度条插件

```shell
## 安装 nprogress 进度条插件
pnpm add nprogress
## 安装 @types/nprogress 类型声明
pnpm add @types/nprogress -D
```

## dayjs 时间处理插件

[dayjs](https://dayjs.fenxianglu.cn/)，Day.js是一个极简的JavaScript库，可以为现代浏览器解析、验证、操作和显示日期和时间，文件大小只有2KB左右。Day.js对国际化有很大的支持

```shell
pnpm add dayjs
```

## normalize.css

normalize.css 是一个用于重置浏览器默认样式的库，使得不同浏览器之间的渲染更加一致

```shell
pnpm add normalize.css
```

### 配置多环境打包

根目录创建三个配置文件，更多环境一样如此操作

- .env.development （开发环境）
- .env.staging （测试环境）
- .env.production （生产环境）

```ts
//.env.development
VITE_APP_ENV = 'development';
VITE_APP_API_URL = /api / xxx务后地服本端 / xxx测试 / xxx生产都行;

//.env.staging
VITE_APP_ENV = 'staging';
VITE_APP_API_URL = xxx测试域名;

//.env.production
VITE_APP_ENV = 'production';
VITE_APP_API_URL = xxx生产域名;
```

```json
// package.json
  "scripts": {
    "dev": "vite",
    "build": "vue-tsc -b && vite build",
    // 新增打包命令 测试 生产 vue-tsc -b：表示 运行 TypeScript 类型检查 去掉也行（最好是别去掉因为本身用的ts项目）
    "build:staging": "vue-tsc -b && vite build --mode staging",
    "build:prod": "vue-tsc -b && vite build --mode production",
  },
```

## 组件名称 以及 扩展 `<script setup>` 语法糖

`vite-plugin-vue-setup-extend` 是一个扩展插件，可以让你在 `<script setup>` 中使用 `defineProps`、`defineEmits`、`defineExpose`、`withDefaults` `inheritAttrs`、`directives` 等等语法糖，并且可以自动导入组件名称，不需要手动导入组件名称，可以直接使用组件名称

```ts
// 给组件定义名称
<script setup name="MyComponent">
import { ref } from 'vue';

const count = ref(0);
</script>
```

## 国际化 vue-i18n

暂无（过多）国际化的需求 为了灵活性 如果公司有国际化业务需求自己基于现有基础上需要加上一个多语言切换功能即可

## 涉及到计算类型 建议使用 bignumber.js

`bignumber.js` 是一个用于精确计算大数字的 `JavaScript` 库。它主要用于处理需要高精度计算的场景，例如金融计算、科学计算、密码学等

## npm 设置代理 & 清空缓存

```shell
# 设置淘宝镜像
npm config set registry https://registry.npmmirror.com
# 查看当前的源
npm config get registry
# 更新 pnpm
npm update -g pnpm
# 强制删除 node_modules
Remove-item -Force -Recurse node_modules
# 清空 npm 缓存
npm cache clean --force
```

## build 名称的 vue-tsc -b

`vue-tsc -b` 用于强制执行 `TypeScript` 编译检查 `-b` 选项通常用于执行 `TypeScript` 的构建任务。具体来说，它会使用 `tsconfig.json` 文件中的配置来编译项目，并进行类型检查。即使有类型错误，`vue-tsc -b` 仍会进行编译，但会对这些错误进行警告或报错

## Vite打包优化

1. 优化打包体积
2. 优化打包速度
3. 字体压缩 (`vite-plugin-fontmin`)
4. 拆包（最小化拆分包）
5. 压缩代码
6. 缓存
7. 预加载 （`vite-plugin-preload 插件【未测试】`/`<link rel="preload" href="xxx.js" as="script"> <link rel="preload" href="xxx.css" as="style">`）
8. 预渲染 （`vite-plugin-prerender 插件【未测试】`）
9. 异步加载
10. 按需加载
11. 代码分割
12. 图片压缩
13. 字体压缩
14. 其他优化 CDN 配置(`vite-plugin-cdn-import`)、骨架屏、网络层面的优化等等

- 参考基准 （在 Vite 5 中，built in 21.22s 的打包时间对于中型项目来说是一个合理的水平，但对于大型项目来说可能是一个较快的水平）
- 小型项目：通常在 5s 以内
- 中型项目：通常在 10s 到 20s 之间
- 大型项目：通常在 20s 以上

## 自动重启 vite 服务

`vite-plugin-restart` 通过监听文件修改，自动重启 vite 服务

```ts
// vite.config.ts
import ViteRestart from 'vite-plugin-restart';
export default {
  plugins: [
    ViteRestart({
      // 一般就是这两个文件
      restart: ['vite.config.js', '.env.development']
    })
  ]
};
```

## live-server 插件

```shell
pnpm add -g live-server
```

`live-server` 是一个轻量级的开发服务器，支持自动刷新和热重载。它非常适合用于本地开发和测试静态网站
`cd dist` 进入到打包后端目录 执行 `live-server` 即可本地模拟服务

```shell
pnpm add vite-plugin-restart -D
```

## 调试工具

```shell
# 安装
pnpm add vconsole -D
```

```ts
// main.ts
import VConsole from 'vconsole';

if (__APP_ENV__ === 'development') {
  new VConsole();
}
```

## Q & A

打包生成后的 `bundle-stats.html` 需要手动删除 再提交 不然 eslint 一直报错 添加了忽略文件也不生效目前

- Q：找不到模块`“path”`或其相应的类型声明
- A：ts提示路径错误，可以尝试安装 `pnpm i @types/node -D` 解决
- Q：`tsconfig.app.json` 和 `tsconfig.node.json` 作用是什么
- A：`tsconfig.app.json` 和 `tsconfig.node.json` 是 `TypeScript` 配置文件，用于分别配置前端应用和 `Node.js` 环境的 `TypeScript` 编译选项。这两个文件的存在是为了更好地分离和定制不同运行环境的 `TypeScript` 配置，而不会相互影响
- A：如果出现这样的情况 `stylelint-config-prettier 9.0.5`
  └── `✕ unmet peer stylelint@">= 11.x < 15": found 16.9.0`
- Q：证明版本不匹配 安装匹配的两个插件的版本即可解决要么移除该不匹配的版本要么降级解决
- Q：`defineStore` 报错 没有与此调用匹配的重载 第 1 个重载(共 3 个)
- A：`"moduleResolution": "bundler"`（vite初始化工程时默认）, 改为 `"moduleResolution": "node"` 即可，`moduleResolution："Classic"`：这是 `TypeScript` 的旧解析策略。它不支持 `Node.js` 模块解析策略，主要用于向后兼容。`"Node"`：这是 TypeScript 的默认解析策略，也是最常用的策略。它遵循 `Node.js` 的模块解析策略，支持 `node_modules` 查找和路径别名（如 `baseUrl` 和 `paths`）。`"Node16"` 或 `"NodeNext"`：这些是较新的解析策略，提供了对 `Node.js` 模块解析的最新支持，包括对 `ECMAScript` 模块（ESM）的支持
- Q：`import dayjs from 'dayjs'`报错 此模块是使用 `“export =” `声明的，只能在使用`“allowSyntheticDefaultImports”`标志时用于默认导入
- A：`tsconfig.json`配置 `"esModuleInterop":true;"allowSyntheticDefaultImports": true` 这允许你使用默认导入来导入 CommonJS 模块 或者命名空间导入 `import * as dayjs from 'dayjs'`

## 特技

1.  Gitee 官方博客 [blog.gitee.com](https://blog.gitee.com)
2.  你可以 [https://gitee.com/explore](https://gitee.com/explore) 这个地址来了解 Gitee 上的优秀开源项目
3.  [GVP](https://gitee.com/gvp) 全称是 Gitee 最有价值开源项目，是综合评定出的优秀开源项目
4.  Gitee 官方提供的使用手册 [https://gitee.com/help](https://gitee.com/help)
5.  Gitee 封面人物是一档用来展示 Gitee 会员风采的栏目 [https://gitee.com/gitee-stars/](https://gitee.com/gitee-stars/)