从0到1构建开源 vue-uniapp-template

创建项目

初始化项目

按照 uni-app 官方文档 的步骤，通过 vue-cli 创建 uni-app + vue + typescript 脚手架：

npx degit dcloudio/uni-preset-vue#vite-ts uniapp-vite-vue3-ts-template

启动项目

创建完成后，使用 VSCode 打开项目并启动：

# 安装依赖
pnpm install
# 启动项目
pnpm  dev:h5

项目启动后，访问 http://localhost:5173 预览效果：

代码规范配置

为了保证项目代码的规范性和一致性，可以为项目配置 ESLint、Stylelint、Prettier 以及 Husky，从而确保代码质量和开发流程的一致性。

集成 ESLint

ESLint 是一款 JavaScript 和 TypeScript 的代码规范工具，能够帮助开发团队保持代码风格一致并减少常见错误。

ESLint 中文网：eslint.nodejs.cn/

安装插件

VSCode 插件市场搜索 ESLint 插件并安装

并且添加到工作区：

配置 ESLint

通过以下命令快速生成 ESLint 配置文件：

npx eslint --init

执行该命令后，ESLint 会通过交互式问题的方式，帮助生成配置文件。针对 9.x 版本，默认会生成基于 Flat Config 格式的 `eslint.config.mjs import globals from "globals"; // 全局变量 import js from "@eslint/js"; // JavaScript 的推荐配置 import tseslint from "typescript-eslint"; // TypeScript 的推荐配置 import pluginVue from "eslint-plugin-vue"; // Vue 的推荐配置 import { defineConfig } from "eslint/config";

export default defineConfig([ { files: ["/*.{js,mjs,cjs,ts,vue}"], plugins: { js }, extends: ["js/recommended"], }, { files: ["/.{js,mjs,cjs,ts,vue}"], languageOptions: { globals: globals.browser }, }, tseslint.configs.recommended, pluginVue.configs["flat/essential"], { files: ["**/.vue"], languageOptions: { parserOptions: { parser: tseslint.parser } }, },

// 添加忽略的目录或文件 { ignores: [ "/dist", "/public", "/node_modules", "/*.min.js", "/.config.mjs", "**/.tsbuildinfo", "/src/manifest.json", ], },

// 自定义规则 { rules: { quotes: ["error", "double"], // 强制使用双引号 "quote-props": ["error", "always"], // 强制对象的属性名使用引号 semi: ["error", "always"], // 要求使用分号 indent: ["error", 2], // 使用两个空格进行缩进 "no-multiple-empty-lines": ["error", { max: 1 }], // 不允许多个空行 "no-trailing-spaces": "error", // 不允许行尾有空格

  // TypeScript 规则
  "@typescript-eslint/no-explicit-any": "off", // 禁用 no-explicit-any 规则，允许使用 any 类型
  "@typescript-eslint/explicit-function-return-type": "off", // 不强制要求函数必须明确返回类型
  "@typescript-eslint/no-empty-interface": "off", // 禁用 no-empty-interface 规则，允许空接口声明
  "@typescript-eslint/no-empty-object-type": "off", // 允许空对象类型

  // Vue 规则
  "vue/multi-word-component-names": "off", // 关闭多单词组件名称的限制
  "vue/html-indent": ["error", 2], // Vue 模板中的 HTML 缩进使用两个空格
  "vue/no-v-html": "off", // 允许使用 v-html (根据实际项目需要)
},

}, ]);  文件，与之前的 .eslintrc` 格式有所不同。

默认生成的 eslint.config.mjs 文件如下所示：

在此基础上，可以根据项目的需求进行一些定制化配置，例如添加忽略规则或自定义的特殊规则。

import globals from "globals"; // 全局变量
import js from "@eslint/js"; // JavaScript 的推荐配置
import tseslint from "typescript-eslint"; // TypeScript 的推荐配置
import pluginVue from "eslint-plugin-vue"; // Vue 的推荐配置
import { defineConfig } from "eslint/config";

export default defineConfig([
  {
    files: ["**/*.{js,mjs,cjs,ts,vue}"],
    plugins: { js },
    extends: ["js/recommended"],
  },
  {
    files: ["**/*.{js,mjs,cjs,ts,vue}"],
    languageOptions: { globals: globals.browser },
  },
  tseslint.configs.recommended,
  pluginVue.configs["flat/essential"],
  {
    files: ["**/*.vue"],
    languageOptions: { parserOptions: { parser: tseslint.parser } },
  },

  // 添加忽略的目录或文件
  {
    ignores: [
      "/dist",
      "/public",
      "/node_modules",
      "**/*.min.js",
      "**/*.config.mjs",
      "**/*.tsbuildinfo",
      "/src/manifest.json",
    ],
  },

  // 自定义规则
  {
    rules: {
      quotes: ["error", "double"], // 强制使用双引号
      "quote-props": ["error", "always"], // 强制对象的属性名使用引号
      semi: ["error", "always"], // 要求使用分号
      indent: ["error", 2], // 使用两个空格进行缩进
      "no-multiple-empty-lines": ["error", { max: 1 }], // 不允许多个空行
      "no-trailing-spaces": "error", // 不允许行尾有空格

      // TypeScript 规则
      "@typescript-eslint/no-explicit-any": "off", // 禁用 no-explicit-any 规则，允许使用 any 类型
      "@typescript-eslint/explicit-function-return-type": "off", // 不强制要求函数必须明确返回类型
      "@typescript-eslint/no-empty-interface": "off", // 禁用 no-empty-interface 规则，允许空接口声明
      "@typescript-eslint/no-empty-object-type": "off", // 允许空对象类型

      // Vue 规则
      "vue/multi-word-component-names": "off", // 关闭多单词组件名称的限制
      "vue/html-indent": ["error", 2], // Vue 模板中的 HTML 缩进使用两个空格
      "vue/no-v-html": "off", // 允许使用 v-html (根据实际项目需要)
    },
  },
]);

添加 ESLint 脚本

为了方便使用 ESLint，可以在 package.json 中添加 lint 脚本命令：

{ "scripts": {  "lint:fix": "eslint --fix  ./src"} }

此脚本会自动修复符合 ESLint 规则的代码问题，并输出检查结果。

测试效果

在 App.vue 文件中声明一个未使用的变量，并运行 pnpm run lint:fix，可以看到 ESLint 提示该变量未使用。如下图所示：

![2bfa6589-d89f-43a5-bfa3-ffcf855d44f6.png](p0-xtjj-private.juejin.cn/tosh

#### 集成 Prettier
Prettier 是一个代码格式化工具，能够和 ESLint 配合使用，确保代码风格统一。

**prettier 中文网**：<https://prettier.nodejs.cn/>

##### 安装插件
VSCode 插件市场搜索 `Prettier - Code formatter` 插件安装

![1bb8a470-5d65-4e1d-ab64-ffbc4140c982.png](https://p6-xtjj-sign.byteimg.com/tos-cn-i-73owjymdk6/48fef1018acf4a78a06578ceef3662d8~tplv-73owjymdk6-jj-mark-v1:0:0:0:0:5o6Y6YeR5oqA5pyv56S-5Yy6IEAg5bKp5p-P:q75.awebp?rk3s=f64ab15b&x-expires=1762249438&x-signature=cHpCnjfy64GctAf70CiiUcsOBO8%3D)

也需要把这个插件添加到工作区

##### 安装依赖

```bash
pnpm install -D prettier eslint-config-prettier eslint-plugin-prettier

• prettier：主要的 Prettier 格式化库。
• eslint-plugin-prettier：将 Prettier 的规则作为 ESLint 的规则来运行。
• eslint-config-prettier：禁用所有与格式相关的 ESLint 规则，以避免和 Prettier 的冲突。

配置 Prettier

项目根目录下新建配置文件 prettier.config.mjs，添加常用规则：

export default {
  printWidth: 100, // 每行最多字符数量，超出换行(默认80)
  tabWidth: 2, // 缩进空格数，默认2个空格
  useTabs: false, // 指定缩进方式，空格或tab，默认false，即使用空格
  semi: true, // 使用分号
  singleQuote: false, // 使用单引号 (true:单引号;false:双引号)
  trailingComma: 'all', // 末尾使用逗号
};

配置忽略文件

项目根目录新建 .prettierignore 文件指定 Prettier 不需要格式化的文件和文件夹

# .prettierignore
node_modules
dist
public
*.min.js

添加格式化脚本

在 package.json 文件中添加：

{ "scripts": { "format": "prettier --write ./src" } }

集成 Stylelint

Stylelint 一个强大的 CSS linter(检查器)，可帮助您避免错误并强制执行约定。

Stylelint 官网：stylelint.io/

安装插件

VSCode 插件搜索 Stylelint 并安装

也需要添加到工作区

安装依赖

pnpm install -D postcss postcss-html postcss-scss stylelint stylelint-config-recommended stylelint-config-recommended-scss stylelint-config-recommended-vue stylelint-config-recess-order stylelint-config-html stylelint-prettier

依赖	说明	备注
postcss	CSS 解析工具，允许使用现代 CSS 语法并将其转换为兼容的旧语法
postcss-html	解析 HTML (类似 HTML) 的 PostCSS 语法	postcss-html 文档
postcss-scss	PostCSS 的 SCSS 解析器	postcss-scss 文档，支持 CSS 行类注释
stylelint	stylelint 核心库	stylelint
stylelint-config-standard	Stylelint 标准共享配置	stylelint-config-standard 文档
stylelint-config-recommended
stylelint-config-recommended-scss	扩展 stylelint-config-recommended 共享配置并为 SCSS 配置其规则	stylelint-config-recommended-scss 文档
stylelint-config-recommended-vue	扩展 stylelint-config-recommended 共享配置并为 Vue 配置其规则	stylelint-config-recommended-vue 文档
stylelint-config-recess-order	提供优化样式顺序的配置	CSS 书写顺序规范
stylelint-config-html	共享 HTML (类似 HTML) 配置，捆绑 postcss-html 并对其进行配置	stylelint-config-html 文档
stylelint-prettier

配置 Stylelint

根目录新建 .stylelintrc.json 文件，配置如下：

{
  "extends": [
    "stylelint-config-recommended",
    "stylelint-config-recommended-scss",
    "stylelint-config-recommended-vue/scss",
    "stylelint-config-html/vue",
    "stylelint-config-recess-order"
  ],
  "plugins": ["stylelint-prettier"],
  "overrides": [
    {
      "files": ["**/*.{vue,html}"],
      "customSyntax": "postcss-html"
    },
    {
      "files": ["**/*.{css,scss}"],
      "customSyntax": "postcss-scss"
    }
  ],

  "rules": {
    "import-notation": "string",
    "selector-class-pattern": null,
    "custom-property-pattern": null,
    "keyframes-name-pattern": null,
    "no-descending-specificity": null,
    "no-empty-source": null,
    "unit-no-unknown": [
      true,
      {
        "ignoreUnits": ["rpx"]
      }
    ],
    "selector-type-no-unknown": [
      true,
      {
        "ignoreTypes": ["page"]
      }
    ],
    "selector-pseudo-class-no-unknown": [
      true,
      {
        "ignorePseudoClasses": ["global", "export", "deep"]
      }
    ],
    "property-no-unknown": [
      true,
      {
        "ignoreProperties": []
      }
    ],
    "at-rule-no-unknown": [
      true,
      {
        "ignoreAtRules": ["apply", "use", "forward"]
      }
    ]
  }
}

配置忽略文件

根目录创建 .stylelintignore 文件，配置忽略文件如下：

*.min.js 
dist
public
node_modules

添加 Stylelint 脚本

package.json 添加 Stylelint 检测指令：

"scripts": { "lint:stylelint": "stylelint \"**/*.{css,scss,vue,html}\" --fix" }

保存自动修复

项目根目录下.vscode/settings.json 文件添加配置：

{ "editor.codeActionsOnSave": { "source.fixAll.stylelint": true }, "stylelint.validate": ["css", "scss", "vue", "html"] }

Git提交规范配置

配置 Husky 的 pre-commit 和 commit-msg 钩子，实现代码提交的自动化检查和规范化。

• pre-commit: 使用 Husky + Lint-staged，在提交前进行代码规范检测和格式化。确保项目已配置 ESLint、Prettier 和 Stylelint。
• commit-msg: 结合 Husky、Commitlint、Commitizen 和 cz-git，生成规范化且自定义的 Git commit 信息。

集成 Husky

Husky 是 Git 钩子工具，可以设置在 git 各个阶段（pre-commit、commit-msg 等）触发。

Husky官网：typicode.github.io/husky/

安装依赖

pnpm add --save-dev husky

初始化

init 命令简化了项目中的 husky 设置。它会在 .husky/ 中创建 pre-commit 脚本，并更 新 package.json 中的 prepare 脚本。

pnpm exec husky init

通过 pre-commit 钩子，可以自动运行各种代码检查工具，在提交代码前强制执行代码质量和样式检查。常见的工具包括：

• eslint：用于检查和修复 JavaScript/TypeScript 代码中的问题。
• stylelint：用于检测和修复 CSS/SCSS 样式问题。

接下来，集成 lint-staged 和 commitlint 来进一步完善开发体验。

集成 lint-staged

lint-staged 是一个工具，专门用于只对 Git 暂存区的文件运行 lint 或其他任务，确保只检查和修复被修改或新增的代码部分，而不会影响整个代码库。这样可以显著提升效率，尤其是对于大型项目

安装依赖

使用以下命令安装 lint-staged：

pnpm add -D lint-staged

配置 lint-staged

在 package.json 中添加 lint-staged 配置，确保在 pre-commit 阶段自动检测暂存的文件：

{
  
  "lint-staged": {
    "*.{js,ts}": [
      "eslint --fix",
      "prettier --write"
    ],
    "*.{cjs,json}": [
      "prettier --write"
    ],
    "*.{vue,html}": [
      "eslint --fix",
      "prettier --write",
      "stylelint --fix"
    ],
    "*.{scss,css}": [
      "stylelint --fix",
      "prettier --write"
    ],
    "*.md": [
      "prettier --write"
    ]
  }
}

在 package.json 的 scripts 部分中，添加用于运行 lint-staged 的命令：

"scripts": { "lint:lint-staged": "lint-staged" }

添加 Husky 钩子

在项目根目录的 .husky/pre-commit 中添加以下命令，确保在提交代码前执行 lint-staged： pnpm run lint:lint-staged

从0到1构建开源 vue-uniapp-template：使用 UniApp + Vue3 + TypeScript 和 VSCoe、CLI 开发跨平台移动端脚手架 - 有来技术 - 博客园