Vue3+Vite5+pinia+Ts+Vue-Router+Eslint9全套搭建规范的移动端项目骨架vite-vue

vite-vue3-h5

介绍

使用 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版本等等，适合快速搭建移动端项目，提升开发效率

安装教程

pnpm intall 安装依赖包
pnpm run dev 启动项目
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）

npm init @eslint/config@latest

prettier 安装

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

pnpm i prettier -D

Stylelint 安装

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

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版本开始就废除了该插件说明该插件已经不再需要了，所以不需要安装了 :::

browserslist 配置文件

根目录创建 .browserslistrc 文件，配置浏览器兼容性，具体配置参考 browserslist

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

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

Husky + Lint-staged

pnpm add husky lint-staged -D

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

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

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

配置 Commitlint + Commitizen + cz-git

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

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','')"

// 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 库

pnpm add vant

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

按需引入vant组件

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'
    })
  ]
});

按需引入组件样式

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

底部安全区适配

<!-- 在 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预处理器方便主题定制

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

移动端适配机型

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

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

# 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 文件夹

# 安装 pinia
pnpm add pinia

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

nprogress 进度条插件

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

dayjs 时间处理插件

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

pnpm add dayjs

normalize.css

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

pnpm add normalize.css

配置多环境打包

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

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

//.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生产域名;

// 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 等等语法糖，并且可以自动导入组件名称，不需要手动导入组件名称，可以直接使用组件名称

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

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

国际化 vue-i18n

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

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

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

npm 设置代理 & 清空缓存

# 设置淘宝镜像
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打包优化

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

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

自动重启 vite 服务

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

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

live-server 插件

pnpm add -g live-server

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

pnpm add vite-plugin-restart -D

调试工具

# 安装
pnpm add vconsole -D

// 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'

仓库地址

鱼樱前端 gitee.com/yuyingqiand…

Vue3+Vite5+pinia+Ts+Vue-Router+Eslint9全套搭建规范的移动端项目骨架