这篇内容是在有道云旧笔记基础上重新整理的 Vue/Vite 工程实践 笔记。原始记录偏碎片化，这里补充了使用场景、阅读顺序和落地时需要注意的边界，方便以后在项目里快速复用。

适用场景 ​

  • Vue/Vite 项目中遇到配置、组件封装、构建或运行时问题时，作为排查入口。
  • 需要把一次性调试经验沉淀成团队内可复用的前端工程实践。
  • 迁移旧项目或升级依赖时，用来对照检查环境变量、插件和组件行为差异。

核心要点 ​

  • 正文已经按 「&x20;创建应用」、「&x20;配置eslint」、「&x20;解决eslint与prettier的冲突」、「&x20;配置styleling」 等小节组织，阅读时可以先定位到当前问题对应的小节。
  • 保留了 13 段可直接参考的代码或命令，主要涉及 bash，复制前需要按当前项目路径、版本和变量名做调整。
  • 涉及命令行操作时，建议先在测试目录或测试环境执行，确认输出符合预期后再应用到生产环境。

创建应用 ​

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
pnpm create vue@latest

√ 请输入项目名称： ... vvf3
√ 是否使用 TypeScript 语法？ ... 否 / 是
√ 是否启用 JSX 支持？ ... 否 / 是
√ 是否引入 Vue Router 进行单页面应用开发？ ... 否 / 是
√ 是否引入 Pinia 用于状态管理？ ... 否 / 是
√ 是否引入 Vitest 用于单元测试？ ... 否 / 是
√ 是否要引入一款端到端（End to End）测试工具？ » 不需要
√ 是否引入 ESLint 用于代码质量检测？ ... 否 / 是
√ 是否引入 Prettier 用于代码格式化？ ... 否 / 是

项目构建完成，可执行以下命令：

  cd vvf3
  pnpm install
  pnpm format
  pnpm dev

配置eslint ​

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
pnpm add eslint -D  # 上文已安装

# 初始化配置
pnpm eslint --init

You can also run this command directly using 'npm init @eslint/config'.
√ How would you like to use ESLint? · problems   
# To check syntax and find problems
√ What type of modules does your project use? · esm
# JavaScript modules (import/export)
√ Which framework does your project use? · vue
#Vue.js
√ Does your project use TypeScript? · No / Yes
# Yes
√ Where does your code run? · browser
# Browser
√ What format do you want your config file to be in? · JavaScript
The config that you've selected requires the following dependencies#:
# JavaScript
@typescript-eslint/eslint-plugin@latest eslint-plugin-vue@latest @typescript-eslint/parser@latest
√ Would you like to install them now? · No / Yes
# Yes
√ Which package manager do you want to use? · pnpm
#pnpm



解决eslint与prettier的冲突 ​

在理想的状态下，eslint与prettier应该各司其职。eslint负责我们的代码质量，prettier负责我们的代码格式。但是在使用的过程中会发现，由于我们开启了自动化的eslint修复与自动化的根据prettier来格式化代码。所以我们已保存代码，会出现屏幕闪一起后又恢复到了报错的状态。

这其中的根本原因就是eslint有部分规则与prettier冲突了，所以保存的时候显示运行了eslint的修复命令，然后再运行prettier格式化，所以就会出现屏幕闪一下然后又恢复到报错的现象。这时候你可以检查一下是否存在冲突的规则。

查阅资料会发现，社区已经为我们提供了一个非常成熟的方案，即

  • eslint-config-prettier
  • eslint-plugin-prettier。
1
2
3
pnpm add eslint-config-prettier eslint-plugin-prettier eslint-plugin-import eslint-plugin-unused-imports -D
# eslint-plugin-import  导入的规则和顺序
# eslint-plugin-unused-imports用于自动删除未使用的导入

在在 .eslintrc.json文件中最后添加对应的配置

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
/* eslint-env node */
require('@rushstack/eslint-patch/modern-module-resolution')

module.exports = {
  root: true,
  env: {
    browser: true,
    es2021: true,
    node: true
  },
  extends: [
    'eslint:recommended',
    'plugin:vue/vue3-essential',
    'plugin:@typescript-eslint/recommended',
    // 必须放在最后面
    'plugin:prettier/recommended'
  ],
  parser: 'vue-eslint-parser',
  parserOptions: {
    ecmaVersion: 'latest',
    parser: '@typescript-eslint/parser',
    sourceType: 'module'
  },
  plugins: ['vue', '@typescript-eslint', 'unused-imports', 'import'],
  rules: {
    // "off" or 0 - 关闭规则
    // "warn" or 1 - 将规则视为一个警告
    // "error" or 2 - 将规则视为一个错误
    eqeqeq: 2, // 强制使用 === 和 !==
    'prettier/prettier': [
      'warn',
      {
        singleQuote: true,
        semi: false,
        trailingComma: 'none',
        endOfLine: 'auto'
      }
    ],
    'no-unused-vars': 0,
    // eslint-plugin-unused-imports用于自动删除未使用的导入
    // '@typescript-eslint/no-unused-vars': 0,
    'unused-imports/no-unused-imports': 1,
    'unused-imports/no-unused-vars': [
      'error',
      {
        vars: 'all',
        args: 'none',
        ignoreRestSiblings: true
      }
    ],
    // 导入模块的顺序
    'import/order': [
      'error',
      {
        pathGroups: [
          {
            pattern: '@/**',
            group: 'external',
            position: 'after'
          }
        ],
        alphabetize: { order: 'asc', caseInsensitive: false },
        'newlines-between': 'always-and-inside-groups',
        warnOnUnassignedImports: true
      }
    ],
    // 导入的依赖不必一定要在dependencies的文件
    // 'import/no-extraneous-dependencies': [
    //   'error',
    //   {
    //     devDependencies: [
    //       '**/*.test.{ts,js}',
    //       '**/*.spec.{ts,js}',
    //       './test/**.{ts,js}',
    //       './scripts/**/*.{ts,js}'
    //     ]
    //   }
    // ],
    'import/extensions': [
      'error',
      'ignorePackages',
      {
        '': 'never',
        js: 'never',
        jsx: 'never',
        ts: 'never',
        tsx: 'never'
      }
    ]
  },
  globals: {
    defineProps: 'readonly'
  }
}

配置styleling ​

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

stylelint v13版本将css, parse CSS(如SCSS,SASS),html内的css(如*.vue中的style)等编译工具都包含在内。但是v14版本没有包含在内，所以需要安装需要的工具

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
pnpm add stylelint postcss postcss-less postcss-scss postcss-html stylelint-config-recommended-less stylelint-config-recommended-scss stylelint-config-standard stylelint-config-standard-vue stylelint-less stylelint-scss stylelint-order -D

# 15版本以后已经包含 stylelint-config-prettier

# package.json增加命令

"scripts": {
    "dev": "vite",
    "build": "run-p type-check \"build-only {@}\" --",
    "preview": "vite preview",
    "test:unit": "vitest",
    "build-only": "vite build",
    "type-check": "vue-tsc --build --force",
    "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore",
    "format": "prettier --write ./**/*.{html,vue,ts,js,json,md}",
    "stylelint": "stylelint \"./**/*.{css,less,scss,postcss,vue,html}\" --fix --cache"
  },

#安装vscode的Stylelint插件

在配置文件中设置
{
  // 开启自动修复
  "editor.codeActionsOnSave": {
    "source.fixAll": false,
    "source.fixAll.eslint": true,
+   "source.fixAll.stylelint": true
  },
  // 保存的时候自动格式化
  "editor.formatOnSave": true,
  // 默认格式化工具选择prettier
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  // 配置该项，新建文件时默认就是space：2
  "editor.tabSize": 2,
  // stylelint校验的文件格式
+ "stylelint.validate": ["css", "less", "vue", "html"]
}

git代码提交规范 commitizen ​

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
pnpm add customizable cz-customizable -D

# 在根目录下新建 .cz-config.cjs 文件并写入配置 之后就可以用 git cz 来代替 git commit

# .cz-config.cjs
module.exports = {
  // 可选类型
  types: [
    { value: 'feat', name: 'feat:     新功能' },
    { value: 'fix', name: 'fix:      修复' },
    { value: 'docs', name: 'docs:     文档变更' },
    { value: 'style', name: 'style:    代码格式(不影响代码运行的变动)' },
    {
      value: 'refactor',
      name: 'refactor: 重构(既不是增加feature，也不是修复bug)'
    },
    { value: 'perf', name: 'perf:     性能优化' },
    { value: 'test', name: 'test:     增加测试' },
    { value: 'chore', name: 'chore:    构建过程或辅助工具的变动' },
    { value: 'revert', name: 'revert:   回退' },
    { value: 'build', name: 'build:    打包' }
  ],
  // 消息步骤
  messages: {
    type: '请选择提交类型:',
    customScope: '请输入修改范围(可选):',
    subject: '请简要描述提交(必填):',
    body: '请输入详细描述(可选):',
    footer: '请输入要关闭的issue(可选):',
    confirmCommit: '确认使用以上信息提交？(y/n/e/h)'
  },
  // 跳过问题
  skipQuestions: ['body', 'footer'],
  // subject文字长度默认是72
  subjectLimit: 72
}

# 在package.json中进行新增

  "scripts": {
    "dev": "vite",
    "build": "run-p type-check \"build-only {@}\" --",
    "preview": "vite preview",
.....
    "commit": "cz-customizable/standalone.js"
  },

"config": {
    "commitizen": {
      "path": "cz-customizable"
    },
    // 指定 .cz-config.cjs 文件路径
    "cz-customizable": {
      "config": ".cz-config.cjs"
    }
 }

# 运行 pnpm commit 就可以使用了



配置husky进行强制git代码提交规范 ​

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93

#安装husky 
pnpm add husky @commitlint/cli @commitlint/config-conventional -D

# commitlint配置文件：
module.exports = {
  // 继承的规则
  extends: ['@commitlint/config-conventional'],
  // 定义规则类型
  rules: {
    // type 类型定义，表示 git 提交的 type 必须在以下类型范围内
    'type-enum': [
      2,
      'always',
      [
        'feat', // 新功能 feature
        'fix', // 修复 bug
        'docs', // 文档注释
        'style', // 代码格式(不影响代码运行的变动)
        'refactor', // 重构(既不增加新功能，也不是修复bug)
        'perf', // 性能优化
        'test', // 增加测试
        'chore', // 构建过程或辅助工具的变动
        'revert', // 回退
        'build' // 打包
      ]
    ],
    // subject 大小写不做校验
    'subject-case': [0]
  }
}




# 初始化配置
npx husky install
npm pkg set scripts.prepare="husky install" #不建议配置因为在install、update等钩子中都会执行，实际只需要初始化一次进行配置
# 执行 npm pkg set scripts.prepare="husky install" 将会设置 prepare 的脚本，并将该脚本的执行命令设置为 husky install，它将会在项目启动时初始化 Git Husky

# 新版本中npx husky install 执行后会生成对应的配置文件就无需 执行 npx husky add .husky/pre-commit 将会生成脚本 ./husky/pre-commit ，它会在 git commit 之前执行脚本，如果脚本报错的情况下将无法提交。



# commit-msg
#!/usr/bin/env sh
. "$(dirname -- "$0")/_/husky.sh"
npx --no-install commitlint --edit

# 
echo "npm test" > .husky/pre-commit


# 以上是老版本，新版本请在 Linux/macOS
echo -e "echo \"commit-msg >> commitlint ...\"\nnpx --no-install commitlint --edit $1" > .husky/commit-msg

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

npx lint-staged
pnpm lint && pnpm format && pnpm style:lint

# 以上是老版本，新版本请在 Linux/macOS
echo -e "echo \"pre-commit >> lint-stage ...\"\nnpx lint-staged" > .husky/pre-commit

#项目初次配置需要生成.husky/pre-commit、.husky/commit-msg等功能配置文件


#安装lint-staged

pnpm add lint-staged -D

#package.json

{
  "lint-staged": {
    "*.{vue,js,jsx,cjs,mjs,ts,tsx,cts,mts,vue}": [
      "pnpm lint && pnpm format && pnpm style:lint",
      "git add"
    ],
    "*.{html,json,md}": [
      "pnpm format",
      "git add"
    ],
    "*.{css,less,scss,postcss,vue,html}": [
      "pnpm style:lint",
      "git add"
    ]
  }
}


实践检查清单 ​

  • 先确认 Vue、Vite、Node、包管理器版本，再判断示例是否需要按当前工程结构调整。
  • 涉及构建或插件配置时，建议同时验证开发环境和生产构建结果。
  • 涉及 UI 或浏览器行为时，至少在桌面端和移动端各验证一次关键路径。
  • 涉及接口、服务端或权限逻辑时，补充失败分支和权限边界测试。

复盘小结 ​

这篇笔记更适合作为问题排查或方案落地前的速查材料。后续如果在真实项目中再次遇到同类问题，可以继续把具体版本、报错信息、最终取舍和验证结果补到对应小节里，让它从代码片段逐步沉淀成完整方案。