# zfshop

**Repository Path**: nbaok/zfshop

## Basic Information

- **Project Name**: zfshop
- **Description**: Vue 3 + TypeScript + Vite + Vant4 构建的移动端商城项目
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: pc_dev_241008
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 1
- **Created**: 2024-10-08
- **Last Updated**: 2025-05-29

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Vue 3 + TypeScript + Vite

This template should help get you started developing with Vue 3 and TypeScript in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.

Learn more about the recommended Project Setup and IDE Support in the [Vue Docs TypeScript Guide](https://vuejs.org/guide/typescript/overview.html#project-setup).

# Node Version

```sh
D:\www>node -v
v20.18.0

D:\www>npm -v
10.8.2

D:\www>pnpm -v
9.12.1
```

# 项目初始化

移动端 UI 框架采用 Vant,安装一些必要的插件

一.首先使用 vite 生成一个脚手架

```sh
npm init vite@latest
```

```sh
# 生产依赖
pnpm install axios vue-router pinia vant
# 开发依赖
pnpm install -D less less-loader
```

关于 pnpm 在 powershell 中报错的说明:

> pnpm : 无法加载文件 D:\dev\nodejs\pnpm.ps1,因为在此系统上禁止运行脚本。

[报错信息说明](https:/go.microsoft.com/fwlink/?LinkID=135170) 中的 about_Execution_Policies

解决办法：

```sh
Set-ExecutionPolicy -ExecutionPolicy Unrestricted -Scope Process
```

## 环境变量与模式

Vite 和 Webpack 类似，都是使用 dotenv 从特定的文件中加载额外的环境变量：

```json
.env // 所有情况下都会加载
.env.development // 开发环境会加载（名称可以通过配置修改）
.env.production // 生产环境会加载（同上）
```

```sh
# .env.development
NODE_ENV = 'development' # production / test
VITE_APP_TITLE = 'XXX'
VITE_APP_BASE_API = '/api'
VITE_SERVE = "XXXX"
```

在客户端中我们使用 import.meta.env 获取环境变量。为了防止意外地将一些环境变量泄漏到客户端，只有以 VITE\_ 为前缀的变量才会暴露到客户端.在服务端，也就是 vite.config.js 中，通过 process.env 获取环境变量。但是 vite 考虑到和其他配置的一些冲突问题，Vite 不会将环境变量直接注入到 process.env 对象下。这时候我们可以手动进行处理：

```sh
# 安装常用 node 模块 ts 声明
pnpm i --save-dev @types/node
```

```javascript
// vite.config.js
import { defineConfig, loadEnv } from 'vite'

export default defineConfig(({ command, mode }) => {
  // loadEnv() 第一个参数为当前模式
  // 第二个参数为环境变量文件所在目录，process.cwd() 返回当前 node 进程的工作目录
  // 第三个参数表示加载以 xxx 开头的环境变量，'' 代表加载所有的环境变量
  const env = loadEnv(mode, process.cwd(), '')
  return {
    // 配置信息
  }
})
```

## Vite配置代理

```javascript
// vite.config.ts
export default defineConfig({
  // ...
  server: {
    proxy: {
      [env.VITE_APP_BASE_API]: {
        target: env.VITE_SERVE,
        changeOrigin: true,
        rewrite: path.replace(new RegExp(`^${env.VITE_APP_BASE_API}`), ''),
      },
    },
  },
})
```

尽管原生 ES-Module 现在得到了广泛支持，但由于嵌套导入会导致额外的网络往返，在生产环境中发布未打包的 ES-Module 效率仍然非常低（即使使用 HTTP/2）。为了在生产环境中获得最佳的加载性能，更好的利用 tree-shaking、懒加载和 chunk 分割等，Vite 把生产环境构建全权交给了 Rollup 。

我们可以通过 构建配置选项 自定义构建过程，比如，通过 build.rollupOptions 直接调整底层的 Rollup 选项 ，使用 build.assetsInlineLimit 修改图片转 base64 的阈值。

```javascript
// vite.config.js
export default defineConfig({
  build: {
    rollupOptions: {
      // https://rollupjs.org/guide/en/#big-list-of-options
    },
    assetsInlineLimit: 4096, // 4kb
  },
})
```

默认情况下，Vite 的目标是支持 原生 ESM script 标签 、支持原生 ESM 动态导入 和 import.meta 的现代浏览器, 但我们可以通过 Vite 自带的 @vitejs/plugin-legacy 插件，来兼容旧版本的浏览器。

```sh
# 必须安装 Terser，@vitejs/plugin-legacy 会使用 Terser 进行压缩
npm install terser -D
```

```javascript
// vite.config.js
import legacy from '@vitejs/plugin-legacy'

export default {
  plugins: [
    legacy({
      // defaults 是 Browserslist 推荐的值
      targets: ['defaults', 'not IE 11'],
    }),
  ],
}
```

## 对 TS 的处理

Vite 仅执行 .ts 文件的转译工作，并不执行任何类型检查。换句话来说，即使 IDE 提示报错，也不影响正常开发和生成环境打包。这样肯定是不行的，不然很难对代码进行有效约束。我们可以使用插件来实现这个功能：

```sh
# 用于检查的插件
npm install vite-plugin-checker -D
# typescript 是 vite-plugin-checker 的依赖
npm install typescript -D
```

```javascript
// vite.config.js
export default defineConfig({
  ...
  plugins: [
    checker({
      typescript: true,
    }),
  ],
})
```

然后在根目录创建 tsconfig.json 文件：

```json
// tsconfig.json
{
  "include": ["src/**/*"] // 需要校验的文件夹
}
```

这样 TS 的报错信息就会在命令行和页面上显示出来，不修正就无法继续往下开发啦！
如果要在类型检查不通过时阻止生产环境打包，直接在 build 命令中添加一个指令即可：

```json
// package.json
"scripts": {
  "dev": "vite",
  "build": "tsc --noEmit && vite build"
}
```

## 「PostCSS」

PostCSS 也是用来处理 CSS 的，只不过它更像是一个工具箱，可以添加各种各样的插件来处理 CSS 。像我们经常遇到的样式兼容性问题，如高级 CSS 语法的降级、前缀补全等，都可以通过 PostCSS 来解决。

```sh
pnpm install postcss-preset-env -D
```

postcss-preset-env 是一个预设环境插件，包含高级 CSS 语法的降级、前缀补全等众多功能。接下来我们在 vite.config.js 中配置一下：

```javascript
// vite.config.js
import postcssPresetEnv from 'postcss-preset-env'

export default defineConfig({
  css: {
    postcss: {
      plugins: [postcssPresetEnv()],
    },
  },
})
```

## 配置别名

```javascript
// vite.config.ts
import { resolve } from 'path'

export default defineConfig({
  // ...
  resolve: {
    alias: {
      '@': resolve(__dirname, 'src'), // 相对路径别名配置，使用 @ 代替 src
    },
  },
})
```

在 `App.vue` 文件中引入文件: `import App from '@/App.vue'` 识别不到模块,需要在 `tsconfig.app.json` 文件中添加修改如下配置:

```json
// tsconfig.app.json 和 tsconfig.app.json
{
  "compilerOptions": {
    // ...
    "baseUrl": "./", // 解析非相对模块的基地址，默认是当前目录
    "paths": {
      //路径映射，相对于baseUrl
      "@/*": ["src/*"]
    },
    "esModuleInterop": true
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.tsx",
    "src/**/*.vue",
    "./auto-imports.d.ts",
    "./components.d.ts"
  ]
}
```

## 移动端适配

```sh
# 生产依赖
pnpm install fastclick amfe-flexible
# 开发依赖
pnpm install -D postcss-pxtorem
pnpm install -D @types/postcss-pxtorem
```

```javascript
// vite.config.ts
import postcssPxToRem from 'postcss-pxtorem'

export default defineConfig({
  // ...
  css: {
    // ...
    postcss: {
      plugins: [
        postcssPxToRem({
          rootValue: 37.5, // UI设计稿的宽度/10, 以 37.5px 为单位
          unitPrecision: 3, // 转换成 px 后保留的小数位数
          propList: ['*'], // 要转换的 CSS 属性
          selectorBlackList: ['ignore'], // 要忽略转换的 CSS 选择器
          replace: true, // 是否直接更换属性值，而不添加备用属性
          mediaQuery: false, // 是否在媒体查询的css代码中也进行转换
          minPixelValue: 2, // 转换的 px 值小于或等于 2px 的不转换
          exclude: /node_modules/i, // 排除node_modules文件夹下的文件
        }),
      ],
    },
  },
})

// 在 main.ts 文件中添加
// REM
import 'lib-flexible'
// FastClick
import FastClick from 'fastclick'
FastClick(document.body)
```

## 按需引入 Vant 组件

查询 [Vant 文档](https://vant-ui.github.io/vant/#/zh-CN) 了解更多

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

```javascript
// vite.config.js
import AutoImport from 'unplugin-auto-import/vite'
import Components from 'unplugin-vue-components/vite'
import { VantResolver } from '@vant/auto-import-resolver'

export default defineConfig(({ mode }) => {
  plugins: [
    vue(),
    AutoImport({
      imports: ['vue', 'vue-router', 'pinia'],
      resolvers: [VantResolver()],
      dts: './auto-imports.d.ts',
    }),
    Components({ resolvers: [VantResolver()], }),
  ],
})
// 在 main.ts 文件中添加
import Vant from 'vant'
import 'vant/lib/index.css'
app.use(Vant)
```

## 一. 配置 eslint

```sh
# 安装
pnpm i -D eslint
# 生成配置文件 .eslint.cjs
npx eslint --init
```

```javascript
// eslint.config.js文件中, `process` 环境变量无法识别 & module.export 校验问题的解决方案:
// eslint.config.js
...
{
  env: { browser: true, es2021: true, node: true, jest: true },
  // eslint 忽略目录
  ignores: [
    '**/node_modules/**/*',
    '**/public/**/*',
    '**/dist/**/*',
    '**/lib/**/*',
    '**/types/**/*.d.ts'
    'auto-imports.d.ts',
    'components.d.ts',
  ],
  rules: { ... }
}
```

## 二. 配置 prettier 和 editorconfig

```sh
# 安装
pnpm install -D eslint-plugin-prettier prettier eslint-config-prettier
```

在根目录下创建 .prettierrc.json 文件,写入配置

```json
// .prettierrc.json
{
  "singleQuote": true,
  "semi": false,
  "bracketSpacing": true,
  "htmlWhitespaceSensitivity": "ignore",
  "endOfLine": "auto",
  "trailingComma": "all",
  "tabWidth": 2,
  "printWidth": 80,
  "bracketSameLine": false,
  "ignorePath": ".prettierignore"
}
```

在根目录下创建 .prettierignore 文件,写入配置

```ignore
/dist/*
/html/*
.local
/node_modules/**
**/*.svg
**/*.sh
/public/*
.vscode/
.idea/
auto-imports.d.ts
components.d.ts
```

在根目录下创建 .editorconfig 文件,写入配置

```sh
// .editorconfig
root = true                                   # 根目录的配置文件，编辑器会由当前目录向上查找，如果找到 `roor = true` 的文件，则不再查找

[*]                                           # 匹配所有的文件
indent_style = space                          # 空格缩进
indent_size = 2                               # 缩进空格为2个
end_of_line = lf                              # 文件换行符是 linux 的 `\n`
charset = utf-8                               # 文件编码是 utf-8
trim_trailing_whitespace = true               # 不保留行末的空格
insert_final_newline = off                    # 文件末尾添加一个空行

curly_bracket_next_line = false               # 大括号不另起一行
spaces_around_operators = true                # 运算符两遍都有空格
indent_brace_style = 1tbs                     # 条件语句格式是 1tbs
spaces_around_brackets = none                 # 表示括号和括号之间应有空格：无空格，仅在括号内，仅在括号外或在括号的两侧（none，inside，outside，both）
max_line_length = 80                          # 在指定的字符数后强制换行。off关闭此功能
[*.{js, ts}]                                  # 对所有的 js 文件生效
quote_type = single                           # 字符串使用单引号

[*.{html, less, css, scss, json}]             # 对所有 html, less, css, json 文件生效
quote_type = double                           # 字符串使用双引号
```

## 三. 配置 stylelint (样式校验)

stylelint 为 css 的 lint 工具。可格式化 css 代码,检查 css 语法错误与不合理的写法,指定 css 书写顺序等。

```sh
# 安装
pnpm add sass sass-loader stylelint postcss postcss-scss postcss-html stylelint-config-prettier stylelint-config-recess-order stylelint-config-recommended-scss stylelint-config-standard stylelint-config-standard-vue stylelint-scss stylelint-order stylelint-config-standard-scss -D
```

在根目录下创建 .stylelintrc.cjs 文件,写入配置

```json
// .stylelintrc.cjs
{
  "singleQuote": true,
  "semi": false,
  "bracketSpacing": true,
  "htmlWhitespaceSensitivity": "ignore",
  "endOfLine": "auto",
  "trailingComma": "all",
  "tabWidth": 2
}
```

在根目录下创建 .stylelintignore 文件,写入配置

```ignore
/node_modules/*
/dist/*
/html/*
/public/*
```

最后配置统一的 prettier 来格式化我们的 js 和 css, html 代码

```json
// package.json
"scripts": {
  "format": "prettier --write \"./**/*.{html,vue,ts,js,json,md}\"",
  "lint:eslint": "eslint src/**/*.{ts,vue} --cache --fix",
  "lint:style": "stylelint src/**/*.{css,scss,vue} --cache --fix"
}
```

## 四. 配置 husky (提交校验一)

安装`husky`

```sh
pnpm install -D husky
```

执行

```sh
git init
npx husky-init
```

会在根目录下的 .husky 目录生成一个下 pre-commit 文件,这个文件里面的命令在我们执行 commit 的时候就会执行

在 `.husky/pre-commit` 文件添加如下命令:

```sh
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpm run format
```

## 四. 配置 commitlint (提交校验二)

对于我们的 commit 信息, 也是有统一规范的, 不能随便写, 要让每个人都按照统一的标准来执行, 我们可以利用 commitlint 来实现。

安装`commitlint`

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

添加配置文件, 新建 commitlint.config.cjs(注意是 cjs), 然后添加下面的代码:

```javascript
module.exports = {
  extends: ['@commitlint/config-conventional'],
  // 校验规则
  rules: {
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新特性、新功能
        'fix', // 修改bug
        'docs', // 文档修改
        'style', // 代码格式修改,注意不是css 修改
        'refactor', // 代码重构
        'perf', // 优化相关,比如提升性能、体验
        'test', // 测试用例修改
        'chore', // 其他修改,比如改变构建流程、或者增加依赖库、工具等
        'revert', // 回滚到上一个版本
        'build', // 编译相关的修改,例如发布版本、对项目构建或者依赖的改动
      ],
    ],
    'type-case': [0],
    'type-empty': [0],
    'scope-empty': [0],
    'scope-case': [0],
    'subject-full-stop': [0, 'never'],
    'subject-case': [0, 'never'],
    'header-max-length': [0, 'always', 72],
  },
}
```

在 `package.json` 中配置 scripts 命令

```json
// 在 scripts 中添加如下代码
"scripts": {
  "commitlint": "commitlint --config commitlint.config.cjs -e -V",
},
```

配置结束,现在当我们填写 commit 信息的时候,前面就需要带着 subject

配置 husky

```sh
npx husky add .husky/commit-msg
```

在生成的 commit-msg 文件中添加下面的命令

```sh
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"

pnpm commitlint
```

当我们 commit 提交信息时就不能再随意写了, 必须是 git commit -m 'fix: xxx' 符合类型的才可以, **需要注意的是类型的后面需要用英文的:,并且冒号后面是需要空一格这个是不能省略的**

## 强制使用 pnpm 包管理器工具

在根目录创建 `scritps/preinstall.js` 文件,添加下面的内容

```javascript
// 规范包管理器工具
if (!/pnpm/.test(process.env.npm_execpath || '')) {
  console.warn(
    `\u001b[33mThis repository must using pnpm as the package manager ` +
      ` for scripts to work properly.\u001b[39m\n`,
  )
  process.exit(1)
}
```

在 `package.json` 中配置 scripts 命令

```json
// 在 scripts 中添加如下代码
"scripts": {
  "preinstall": "node ./scripts/preinstall.js",
},
```

当我们使用 npm 或者 yarn 来安装包的时候, 就会报错了。原理就是在 install 的时候会触发 preinstall(npm 提供的生命周期钩子)这个文件里面的代码。

## 通过第三方插件 vite-plugin-vue-setup-extend 实现组件命名

```sh
# 安装
pnpm i -D vite-plugin-vue-setup-extend
```

```javascript
// 在 vite.config.ts 中引入
import vueSetupExtend from 'vite-plugin-vue-setup-extend'

export default defineConfig({
  // ...
  plugins: [
    // ...
    vueSetupExtend(),
  ],
})

// 在 App 组件中添加 'name'属性
<script setup lang="ts" name="App"></script>
```

## 重置全局样式

在 `src/assets` 目录下创建 `styles` 文件夹,创建三个文件: 重置样式: `reset.scss` , 样式变量: `variable.scss`, 全局样式: `index.scss`, 例如在全局样式中我们可以修改 elementPlus 设置的滚动条样式. 并在 `main.ts` 文件中引入全局样式.

```javascript
// vite.config.ts
export default defineConfig({
  // ...
  css: {
    // ...
    preprocessorOptions: {
      scss: {
        javascriptEnabled: true,
        additionalData: '@import "./src/assets/styles/variable.scss";',
      },
    },
  },
})

// main.ts
import '@/styles/index.scss'
```

```scss
// styles/variable.scss
// 定义的样式全局变量
$base_menu_bgcolor: #001529;

// styles/index.scss
// 自定义滚动条外观，可以直接引用样式全局变量
::-webkit-scrollbar {
  width: 10px;
}

::-webkit-scrollbar-track {
  background-color: $base_menu_bgcolor;
}

::-webkit-scrollbar-thumb {
  width: 10px;
  background-color: aqua;
  border-radius: 10px;
}
```

## 自动引入全局组件

在 `src/components`目录下新建 `index.ts`文件

```javascript
// 自动注册全局组件
const modules = import.meta.glob('../components/**/index.vue', {
  eager: false,
  import: 'default'
})

const allGlobalComponet: any = {}
Object.entries(modules).map(([filename, component]: [any, any]) => {
  filename = filename.replace('./', '').replace('/index.vue', '').split('/')
  filename = filename[filename.length - 1]
  allGlobalComponet[filename] = component
})

export default {
  install(app: any) {
    Object.keys(allGlobalComponet).forEach(key => {
      app.component(key, allGlobalComponet[key])
    })
  }
}
```

入口文件中用 **app.use** 时,会自动调用模块的 **install** 方法并注入根组件 **app**

```javascript
...
import globalComponent from '@/components'
app.use(globalComponent)
```

## Vue3 封装组件方式一

在 `components`文件夹下对应创建组件(.vue)及脚本(.ts),例如:

```javascript
// components/Toast/Tost.vue (正常创建Vue3组件)
<template>...</template>
<script setup>...</script>

// components/Toast/index.ts
// 导入创建的 Vue3 组件
import Toast from './Toast.vue'
import { createVNode, render } from 'vue'

// @params title 组件需要接收的参数
export default function $toast(title) {
  // 创建虚拟 DOM 对象, 并传入组件需要的参数
  let vnode = createVNode(Toast, { title })
  // 虚拟 DOM 渲染为真实 DOM
  // let frag = document.createDocumentFragment()
  let Divbox = document.createElement('div')
  render(vnode, Divbox)
  // 插入到 body 中
  document.body.appendChild(Divbox)
}

export default function $toast(title) {
  if(Divbox) {

  }
}
```

> 调用: 直接导入方法调用即可

## Pinia持久化存储

> [参考CSDN](https://blog.csdn.net/H524268015wsw/article/details/134571995)

（1）安装依赖

```sh
pnpm install -D pinia-plugin-persistedstate
```

（2）将插件添加到 pinia 实例上

```javascript
import { createPinia } from 'pinia' //引入pinia
import piniaPluginPersistedstate from 'pinia-plugin-persistedstate' //引入持久化插件

const pinia = createPinia() //创建pinia实例
pinia.use(piniaPluginPersistedstate) //将插件添加到 pinia 实例上

export default pinia //导出pinia用于main.js注册
```

（3）用法

1.基本使用
创建 Store 时，将 persist 选项设置为 true，整个 Store 将使用默认持久化配置保存。

```javascript
const useUserInfoStore = defineStore('userInfo', {
  ...
  persist: true,
})
```

2.高级使用

```javascript
const useUserInfoStore = defineStore('userInfo', {
  ...
  persist: {
    key: 'piniaStore', //存储名称
    storage: sessionStorage, // 存储方式
    paths: ['username', ...], //指定 state 中哪些数据需要被持久化。[] 表示不持久化任何状态，undefined 或 null 表示持久化整个 state
  },
})
```

## TS 装饰器配置问题

> SyntaxError: Invalid or unexpected token (at useLocalStorage.ts:43:3)

```javascript
// tsconfig.app.json 添加以下配置重启服务后解决
{
  "compilerOptions": {
    // ...
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
  }
}
```