development-guide.md 9.48 KB

Raw Blame History Permalink



Taro 小程序开发配置指南


配置概览

项目已配置完整的代码质量保障体系：


✅ 已创建的配置文件


1. ESLint 配置（.eslintrc.js）


Vue 3 推荐规则
Taro 小程序适配规则
代码风格检查
潜在错误检测


2. Prettier 配置（.prettierrc）


代码格式化规则
统一代码风格
与 ESLint 无冲突集成


3. EditorConfig 配置（.editorconfig）


编辑器统一配置
缩进、换行符等


4. lint-staged 配置（.lintstagedrc.js）


Git 暂存文件检查
仅检查本次修改的文件


5. Husky 配置（scripts/setup-husky.sh）


Git Hooks 自动化
提交前自动检查


快速开始


步骤 1：安装依赖

# 安装 ESLint 相关依赖
pnpm add -D eslint prettier eslint-plugin-vue @vue/eslint-config-prettier

# 安装 Husky 和 lint-staged
pnpm add -D husky lint-staged


步骤 2：初始化 Husky

# 方式 1：使用自动安装脚本
bash scripts/setup-husky.sh

# 方式 2：手动安装
npx husky install
npx husky add .husky/pre-commit "pnpm lint-staged"
npx husky add .husky/commit-msg "npx commitlint --edit \$1"


步骤 3：更新 package.json

在 package.json 的 scripts 中添加：

{
  "scripts": {
    "dev:weapp": "npm run build:weapp -- --watch",
    "build:weapp": "taro build --type weapp",
    "lint": "eslint \"src/**/*.{js,jsx,vue,ts,tsx}\" --fix",
    "lint:no-fix": "eslint \"src/**/*.{js,jsx,vue,ts,tsx}\"",
    "format": "prettier --write \"src/**/*.{js,jsx,vue,ts,tsx,less,css,json,md}\"",
    "format:check": "prettier --check \"src/**/*.{js,jsx,vue,ts,tsx,less,css,json,md}\"",
    "prepare": "husky install"
  }
}


使用说明


日常开发


1. 开发前检查

# 启动开发服务器
pnpm dev:weapp

# 代码会自动检查，但有错误时不会阻止编译


2. 提交代码

# 添加文件到暂存区
git add .

# 提交代码（会自动运行 lint-staged）
git commit -m "feat: 添加新功能"

# 如果检查失败，修复后再次提交
git add .
git commit -m "feat: 添加新功能"


3. 手动检查代码

# 检查并自动修复
pnpm lint

# 仅检查不修复
pnpm lint:no-fix

# 格式化代码
pnpm format

# 检查代码格式
pnpm format:check


跳过检查（不推荐）

# 跳过 lint-staged 检查
git commit --no-verify -m "feat: 临时提交"

# ⚠️ 注意：仅用于紧急情况，平时不要使用


编辑器集成


VS Code


1. 安装插件

推荐安装以下 VS Code 插件：

{
  "recommendations": [
    "dbaeumer.vscode-eslint",        // ESLint
    "esbenp.prettier-vscode",        // Prettier
    "EditorConfig.EditorConfig",     // EditorConfig
    "Vue.volar",                     // Vue 语言支持
    "taro.vscode-tarojs"             // Taro 开发工具
  ]
}


2. 配置 VS Code

创建 .vscode/settings.json：

{
  // ESLint
  "editor.formatOnSave": false,
  "editor.codeActionsOnSave": {
    "source.fixAll.eslint": true
  },

  // Prettier
  "[javascript]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[vue]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },
  "[json]": {
    "editor.defaultFormatter": "esbenp.prettier-vscode"
  },

  // Vue
  "volar.autoCompleteRefs": true,
  "volar.codeLens.pugTools": false,
  "volar.completion.autoImportComponent": true,

  // 文件
  "files.eol": "\n",
  "files.trimTrailingWhitespace": true,
  "files.insertFinalNewline": true
}


3. 配置 VS Code 任务

创建 .vscode/tasks.json：

{
  "version": "2.0.0",
  "tasks": [
    {
      "label": "Lint: 检查并修复",
      "type": "npm",
      "script": "lint",
      "problemMatcher": []
    },
    {
      "label": "Format: 格式化代码",
      "type": "npm",
      "script": "format",
      "problemMatcher": []
    },
    {
      "label": "Dev: 启动微信小程序",
      "type": "npm",
      "script": "dev:weapp",
      "problemMatcher": []
    }
  ]
}


WebStorm / IntelliJ IDEA


启用 ESLint：


Settings → Languages & Frameworks → JavaScript → Code Quality Tools → ESLint
选择 "Automatic ESLint configuration"
勾选 "Run eslint --fix on save"


启用 Prettier：


Settings → Languages & Frameworks → JavaScript → Prettier
选择 "Run on save for files"
勾选 "On code reformat"


启用 EditorConfig：


Settings → Editor → Code Style → EditorConfig
勾选 "Enable EditorConfig support"


配置详解


ESLint 规则说明


Vue 相关规则

'vue/multi-word-component-names': 'off', // 允许单词组件名（如 Home.vue）
'vue/no-v-html': 'warn', // 警告使用 v-html（XSS 风险）
'vue/require-default-prop': 'off', // 不强制 prop 默认值
'vue/no-unused-vars': 'warn', // 警告未使用的变量


通用规则

'no-console': process.env.NODE_ENV === 'production' ? 'warn' : 'off', // 生产环境警告 console
'no-debugger': process.env.NODE_ENV === 'production' ? 'error' : 'off', // 生产环境禁止 debugger
'prefer-const': 'error', // 优先使用 const
'no-var': 'error', // 禁止使用 var
'eqeqeq': ['error', 'always'], // 强制使用 ===
'semi': ['error', 'never'], // 不使用分号
'quotes': ['error', 'single'], // 使用单引号


Prettier 规则说明

{
  "semi": false,           // 不使用分号
  "singleQuote": true,     // 使用单引号
  "trailingComma": "none", // 不使用尾随逗号
  "printWidth": 100,       // 每行最大 100 字符
  "tabWidth": 2,           // 缩进 2 空格
  "endOfLine": "lf"        // 使用 LF 换行符
}


常见问题


Q1: Husky 钩子不生效

问题：提交代码时没有自动运行检查

解决方案：

# 1. 检查 Husky 是否安装
ls -la .husky/

# 2. 重新安装 Husky
pnpm add -D husky
npx husky install

# 3. 添加 pre-commit 钩子
npx husky add .husky/pre-commit "pnpm lint-staged"

# 4. 检查钩子文件
cat .husky/pre-commit


Q2: ESLint 和 Prettier 冲突

问题：ESLint 和 Prettier 对同一处代码有不同规则

解决方案：

# 安装 @vue/eslint-config-prettier
pnpm add -D @vue/eslint-config-prettier

# 在 .eslintrc.js 中添加
{
  "extends": [
    'plugin:vue/vue3-recommended',
    '@vue/eslint-config-prettier' // 放在最后
  ]
}


Q3: lint-staged 检查所有文件

问题：每次提交都检查所有文件，很慢

解决方案：

# 确保 lint-staged 配置正确
cat .lintstagedrc.js

# 应该配置为：
{
  "*.{js,jsx,vue}": ["eslint --fix", "prettier --write"]
}


Q4: 提交被阻止，但不想修复

问题：代码有问题但想临时提交

解决方案：

# ⚠️ 不推荐，仅用于紧急情况
git commit --no-verify -m "feat: 临时提交"


Q5: Taro API 报 ESLint 错误

问题：使用了 wx 全局变量报错

解决方案：

// .eslintrc.js 中已配置
globals: {
  wx: 'readonly',
  getCurrentPages: 'readonly',
  getApp: 'readonly'
}


最佳实践


1. 提交前自检

# 1. 拉取最新代码
git pull origin develop

# 2. 运行检查
pnpm lint
pnpm format:check

# 3. 运行测试（如果有）
pnpm test

# 4. 提交代码
git add .
git commit -m "feat: 添加新功能"


2. Commit 信息规范

推荐使用 Conventional Commits 格式：

feat: 新功能
fix: 修复 bug
docs: 文档更新
style: 代码格式（不影响代码运行的变动）
refactor: 重构（既不是新增功能，也不是修改 bug 的代码变动）
test: 测试相关
chore: 构建过程或辅助工具的变动


示例：

git commit -m "feat(booking): 添加预约日期选择功能"
git commit -m "fix(auth): 修复登录时 token 未持久化的问题"
git commit -m "docs: 更新开发文档"


3. 代码审查清单

在提交 PR 前检查：


 代码已通过 ESLint 检查

 代码已通过 Prettier 格式化

 无 console.log 或 debugger


 无注释掉的代码

 代码有必要的注释

 测试已通过（如果有）

 文档已更新（如需要）


团队协作


统一开发环境

确保团队成员使用相同的配置：

# 1. 克隆项目
git clone <repo-url>

# 2. 安装依赖
pnpm install

# 3. 初始化 Husky
pnpm prepare

# 4. 安装 VS Code 插件
code --install-extension dbaeumer.vscode-eslint
code --install-extension esbenp.prettier-vscode
code --install-extension Vue.volar


代码审查流程


开发者：提交代码前运行 pnpm lint


Husky：自动运行 lint-staged


CI/CD：运行完整的 pnpm lint 和 pnpm test


审查者：检查代码质量和规范

合并：通过所有检查后合并


持续改进


定期更新依赖

# 检查过时的依赖
pnpm outdated

# 更新依赖
pnpm update

# 更新主要版本
pnpm upgrade --latest


自定义规则

根据团队需求调整规则：

// .eslintrc.js
rules: {
  // 添加团队特定规则
  'custom-rule-name': 'error'
}


参考资源


ESlint 官方文档
Prettier 官方文档
EditorConfig 官方文档
Husky 官方文档
lint-staged 官方文档
Vue ESLint 官方插件
Conventional Commits