前端工程化体系学习指南 - 从实践到原理

// 开发者 A 用 VS Code，tab 转 2 个空格
function hello() {
··console.log('A')
}

// 开发者 B 用 WebStorm，tab 转 4 个空格
function hello() {
····console.log('B')
}

// Git 提交时产生大量无意义的 diff

// ❌ 声明了变量但没使用
const userName = 'Tom'

// ❌ 使用了未声明的变量
console.log(userNmae)  // 拼写错误

// ❌ 使用了 == 而不是 ===
if (value == null) { }

// ❌ 函数复杂度太高
function complex() {
  if (...) {
    if (...) {
      if (...) {
        // 100 行嵌套代码
      }
    }
  }
}

// ✅ ESLint 会立即提示
const userName = 'Tom'  // ⚠️ 'userName' is assigned a value but never used

// eslint.config.js
import antfu from '@antfu/eslint-config'

export default antfu()

const a = 1  // 应该显示警告：变量未使用
console.log(b)  // 应该显示错误：变量未定义

// 源代码
const a = 1

// 转换为 AST（简化版）
{
  type: 'VariableDeclaration',
  kind: 'const',
  declarations: [{
    type: 'VariableDeclarator',
    id: { type: 'Identifier', name: 'a' },
    init: { type: 'Literal', value: 1 }
  }]
}

// .eslintrc.js
module.exports = {
  extends: ['eslint:recommended'],
  rules: {
    'semi': ['error', 'never'],
  }
}

// eslint.config.js
import antfu from '@antfu/eslint-config'

export default antfu({
  // 类型安全
  typescript: {
    tsconfigPath: 'tsconfig.json',
    overrides: {
      'ts/no-unsafe-assignment': 'off',
    }
  },

  // Vue 支持
  vue: true,

  // 格式化
  formatters: {
    css: true,
    html: true,
    markdown: 'prettier',
  },

  // 忽略文件
  ignores: [
    '**/dist',
    '**/node_modules',
    '**/.git',
  ],
})

// eslint.config.js
import antfu from '@antfu/eslint-config'

export default antfu({
  // 关闭某些规则
  rules: {
    'no-console': 'off',  // 允许使用 console
    'no-debugger': 'warn',  // debugger 只警告不报错
    'vue/multi-word-component-names': 'off',  // 允许单词组件名
  },
})

// eslint.config.js
import antfu from '@antfu/eslint-config'

export default antfu({
  ignores: [
    '**/dist',
    '**/node_modules',
    '**/.git',
    '**/coverage',
    '**/*.min.js',
  ],
})

// eslint.config.js
import prettier from 'eslint-config-prettier'

export default [
  // ... 其他配置
  prettier,  // 放在最后，关闭与 Prettier 冲突的规则
]

// 禁用下一行的 ESLint 检查
// eslint-disable-next-line
console.log('debug')

// 禁用某个规则
// eslint-disable-next-line no-console
console.log('debug')

// 禁用整个文件
/* eslint-disable */

// 禁用文件中的某个规则
/* eslint-disable no-console */

// 错误级别：
// 'off' 或 0  - 关闭规则
// 'warn' 或 1 - 警告（不会导致程序退出）
// 'error' 或 2 - 错误（会导致程序退出）

export default antfu({
  rules: {
    'no-console': 'warn',  // 只警告，不报错
    'no-debugger': 'error',  // 报错
    'no-unused-vars': 'off',  // 关闭
  },
})

export default {
  languageOptions: {
    parser: '@typescript-eslint/parser',
    parserOptions: {
      ecmaVersion: 'latest',
      sourceType: 'module',
      ecmaFeatures: {
        jsx: true,
        globalReturn: false,
      },
      // TypeScript 特有配置
      project: './tsconfig.json',
      extraFileExtensions: ['.vue'],
    }
  }
}

import pluginVue from 'eslint-plugin-vue'
import pluginImport from 'eslint-plugin-import'
import pluginUnusedImports from 'eslint-plugin-unused-imports'

export default [
  {
    plugins: {
      vue: pluginVue,
      import: pluginImport,
      'unused-imports': pluginUnusedImports,
    },
    rules: {
      // 使用插件规则
      'vue/multi-word-component-names': 'off',
      'import/order': ['error', {
        'groups': ['builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
        'newlines-between': 'always',
      }],
      'unused-imports/no-unused-imports': 'error',
    }
  }
]

export default [
  {
    rules: {
      // 错误级别：'off' | 0, 'warn' | 1, 'error' | 2
      
      // === 代码质量规则 ===
      'no-console': ['warn', { allow: ['warn', 'error'] }],
      'no-debugger': 'error',
      'no-unused-vars': ['error', { 
        vars: 'all',
        args: 'after-used',
        ignoreRestSiblings: true,
      }],
      'no-empty': ['error', { allowEmptyCatch: true }],
      'prefer-const': ['error', { destructuring: 'all' }],
      
      // === 代码风格规则 ===
      'semi': ['error', 'never'],
      'quotes': ['error', 'single', { avoidEscape: true }],
      'comma-dangle': ['error', 'always-multiline'],
      'indent': ['error', 2, { SwitchCase: 1 }],
      
      // === TypeScript 规则 ===
      'ts/no-explicit-any': 'warn',
      'ts/no-non-null-assertion': 'off',
      'ts/consistent-type-imports': ['error', {
        prefer: 'type-imports',
        disallowTypeAnnotations: false,
      }],
      
      // === Vue 规则 ===
      'vue/multi-word-component-names': 'off',
      'vue/no-v-html': 'off',
      'vue/require-default-prop': 'off',
      'vue/component-tags-order': ['error', {
        order: ['script', 'template', 'style'],
      }],
    }
  }
]

// eslint-plugin-custom/rules/no-console-time.js
module.exports = {
  meta: {
    type: 'problem',
    docs: {
      description: '禁止使用 console.time，请使用性能监控 SDK',
      category: 'Best Practices',
    },
    messages: {
      noConsoleTime: '禁止使用 {{method}}，请使用 Performance.measure()',
    },
    schema: [],
  },
  
  create(context) {
    return {
      // 访问成员表达式节点
      MemberExpression(node) {
        // 检查是否是 console.time 或 console.timeEnd
        if (
          node.object.name === 'console' &&
          (node.property.name === 'time' || node.property.name === 'timeEnd')
        ) {
          context.report({
            node,
            messageId: 'noConsoleTime',
            data: {
              method: `console.${node.property.name}`,
            },
          })
        }
      },
    }
  },
}

// eslint.config.js
import customPlugin from './eslint-plugin-custom/index.js'

export default [
  {
    plugins: {
      custom: customPlugin,
    },
    rules: {
      'custom/no-console-time': 'error',
    },
  },
]

// 关闭耗时的类型检查规则
export default [
  {
    rules: {
      // 这些规则需要完整的类型信息，很慢
      'ts/no-unsafe-assignment': 'off',
      'ts/no-unsafe-member-access': 'off',
      'ts/no-unsafe-call': 'off',
    }
  }
]

// 开发者 A 的代码
const user = {name: "Tom",age: 18,city: "Beijing"};
if(user.age>18){console.log("Adult")}

// 开发者 B 的代码
const user = {
  name: 'Tom',
  age: 18,
  city: 'Beijing',
}

if (user.age > 18) {
  console.log('Adult')
}

// .prettierrc.js
export default {
  semi: false,              // 不要分号
  singleQuote: true,        // 单引号
  printWidth: 100,          // 每行最多 100 字符
  trailingComma: 'all',     // 尾随逗号
  arrowParens: 'avoid',     // 箭头函数参数只有一个时省略括号
  endOfLine: 'lf',          // 换行符
}

const user={name:"Tom",age:18};if(user.age>18){console.log("Adult")}

const user = { name: 'Tom', age: 18 }
if (user.age > 18) {
  console.log('Adult')
}

// .prettierrc.js
export default {
  // 基础配置
  semi: false,
  singleQuote: true,
  printWidth: 100,
  trailingComma: 'all',
  arrowParens: 'avoid',
  
  // 换行符
  endOfLine: 'lf',
  
  // Vue 特定
  vueIndentScriptAndStyle: false,
  
  // 覆盖特定文件
  overrides: [
    {
      files: '*.json',
      options: {
        printWidth: 80,
      }
    },
    {
      files: '*.md',
      options: {
        proseWrap: 'never',
      }
    }
  ]
}

// eslint.config.js
import prettier from 'eslint-plugin-prettier'
import configPrettier from 'eslint-config-prettier'

export default [
  configPrettier, // 关闭 ESLint 中与 Prettier 冲突的规则
  {
    plugins: {
      prettier,
    },
    rules: {
      'prettier/prettier': 'error', // 将 Prettier 错误显示为 ESLint 错误
    }
  }
]

// stylelint.config.js
export default {
  extends: [
    'stylelint-config-standard',
    'stylelint-config-recommended-vue',
  ],
  
  rules: {
    // 颜色格式
    'color-hex-length': 'short',
    'color-no-invalid-hex': true,
    
    // 选择器
    'selector-class-pattern': '^[a-z][a-zA-Z0-9]*$', // camelCase
    'selector-max-id': 0, // 禁止 ID 选择器
    
    // 属性顺序
    'order/properties-order': [
      'position',
      'top',
      'right',
      'bottom',
      'left',
      'display',
      'flex',
      // ... 更多属性
    ],
    
    // Vue 特定
    'vue/no-deprecated-slot-attribute': true,
  },
  
  // 忽略文件
  ignoreFiles: [
    '**/*.js',
    '**/*.jsx',
    '**/*.tsx',
    '**/*.ts',
    'dist/**',
  ],
}

// 开发者直接提交了这样的代码
const a=1
console.log(b)  // 未定义的变量
debugger  // 调试代码忘记删除

// .lintstagedrc.js
export default {
  // JavaScript/TypeScript 文件
  '*.{js,jsx,ts,tsx}': [
    'eslint --fix',
    'vitest related --run', // 运行相关测试
  ],
  
  // Vue 文件
  '*.vue': [
    'eslint --fix',
    'stylelint --fix',
  ],
  
  // 样式文件
  '*.{css,scss,less}': [
    'stylelint --fix',
  ],
  
  // Markdown 文件
  '*.md': [
    'markdownlint --fix',
  ],
  
  // 图片压缩
  '*.{png,jpg,jpeg}': [
    'imagemin',
  ],
}

// 防止 lint-staged 运行时间过长
export default {
  '*.{js,ts,vue}': (filenames) => {
    // 限制最多处理 50 个文件
    const files = filenames.length > 50 
      ? filenames.slice(0, 50) 
      : filenames
    
    return [
      `eslint --fix ${files.join(' ')}`,
      `vitest related ${files.join(' ')} --run`,
    ]
  },
}

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  
  rules: {
    // 类型枚举
    'type-enum': [
      2,
      'always',
      [
        'feat',      // 新功能
        'fix',       // 修复 bug
        'docs',      // 文档更新
        'style',     // 代码格式（不影响代码运行）
        'refactor',  // 重构
        'perf',      // 性能优化
        'test',      // 测试相关
        'build',     // 构建系统或外部依赖
        'ci',        // CI 配置
        'chore',     // 其他不修改 src 或 test 的更改
        'revert',    // 回退
      ],
    ],
    
    // 主题不能为空
    'subject-empty': [2, 'never'],
    
    // 主题最大长度
    'subject-max-length': [2, 'always', 100],
    
    // 类型必须小写
    'type-case': [2, 'always', 'lower-case'],
    
    // scope 必须小写
    'scope-case': [2, 'always', 'lower-case'],
  },
}

// commitlint.config.js
export default {
  extends: ['@commitlint/config-conventional'],
  
  rules: {
    // 类型枚举
    'type-enum': [
      2,
      'always',
      [
        'feat',      // 新功能
        'fix',       // 修复 bug
        'docs',      // 文档更新
        'style',     // 代码格式（不影响代码运行）
        'refactor',  // 重构
        'perf',      // 性能优化
        'test',      // 测试相关
        'build',     // 构建系统或外部依赖
        'ci',        // CI 配置
        'chore',     // 其他不修改 src 或 test 的更改
        'revert',    // 回退
      ],
    ],
    
    // 主题不能为空
    'subject-empty': [2, 'never'],
    
    // 主题最大长度
    'subject-max-length': [2, 'always', 100],
    
    // 类型必须小写
    'type-case': [2, 'always', 'lower-case'],
    
    // scope 必须小写
    'scope-case': [2, 'always', 'lower-case'],
  },
}

// .czrc.js
export default {
  alias: {
    fd: 'docs: fix typos',
  },
  
  messages: {
    type: '选择你要提交的类型 :',
    scope: '选择一个提交范围（可选）:',
    customScope: '请输入自定义的提交范围 :',
    subject: '填写简短精炼的变更描述 :\n',
    body: '填写更加详细的变更描述（可选）。使用 "|" 换行 :\n',
    breaking: '列举非兼容性重大的变更（可选）。使用 "|" 换行 :\n',
    footerPrefixSelect: '选择关联 issue 前缀（可选）:',
    customFooterPrefix: '输入自定义 issue 前缀 :',
    footer: '列举关联 issue (可选) 例如: #31, #I3244 :\n',
    confirmCommit: '是否提交或修改 commit ?',
  },
  
  types: [
    { value: 'feat', name: 'feat:     ✨ 新功能', emoji: ':sparkles:' },
    { value: 'fix', name: 'fix:      🐛 Bug 修复', emoji: ':bug:' },
    { value: 'docs', name: 'docs:     📝 文档更新', emoji: ':memo:' },
    { value: 'style', name: 'style:    💄 代码格式', emoji: ':lipstick:' },
    { value: 'refactor', name: 'refactor: ♻️  代码重构', emoji: ':recycle:' },
    { value: 'perf', name: 'perf:     ⚡️ 性能优化', emoji: ':zap:' },
    { value: 'test', name: 'test:     ✅ 测试相关', emoji: ':white_check_mark:' },
    { value: 'build', name: 'build:    📦️ 构建相关', emoji: ':package:' },
    { value: 'ci', name: 'ci:       🎡 CI 配置', emoji: ':ferris_wheel:' },
    { value: 'chore', name: 'chore:    🔨 其他修改', emoji: ':hammer:' },
    { value: 'revert', name: 'revert:   ⏪️ 回退代码', emoji: ':rewind:' },
  ],
  
  scopes: [
    { value: 'auth', name: 'auth:       认证模块' },
    { value: 'user', name: 'user:       用户模块' },
    { value: 'order', name: 'order:      订单模块' },
    { value: 'components', name: 'components: 组件相关' },
    { value: 'utils', name: 'utils:      工具函数' },
    { value: 'deps', name: 'deps:       依赖更新' },
    { value: 'config', name: 'config:     配置文件' },
  ],
}

// === 1. 全局函数时代（史前时代）===
function sayHello() {
  console.log('Hello')
}

// 问题：全局污染、命名冲突、依赖关系不明确


// === 2. 命名空间模式 ===
var MyApp = {
  utils: {
    sayHello: function() {
      console.log('Hello')
    }
  }
}

// 问题：仍然是全局变量，本质上没解决污染


// === 3. IIFE 模式 ===
var module = (function() {
  var privateVar = 'private'
  
  return {
    publicMethod: function() {
      return privateVar
    }
  }
})()

// 优点：真正的私有作用域
// 问题：依赖关系仍不明确


// === 4. CommonJS（Node.js）===
// math.js
module.exports = {
  add: (a, b) => a + b
}

// main.js
const math = require('./math')
math.add(1, 2)

// 特点：同步加载，适合服务端


// === 5. AMD（RequireJS）===
define(['jquery', './math'], function($, math) {
  return {
    calculate: function() {
      return math.add(1, 2)
    }
  }
})

// 特点：异步加载，适合浏览器


// === 6. UMD（通用模块）===
(function (root, factory) {
  if (typeof define === 'function' && define.amd) {
    // AMD
    define(['jquery'], factory)
  } else if (typeof module === 'object' && module.exports) {
    // CommonJS
    module.exports = factory(require('jquery'))
  } else {
    // 全局变量
    root.myModule = factory(root.jQuery)
  }
}(this, function ($) {
  return {
    method: function() {}
  }
}))


// === 7. ES Modules（现代标准）===
// math.js
export const add = (a, b) => a + b
export const subtract = (a, b) => a - b
export default { add, subtract }

// main.js
import math, { add } from './math.js'

// 特点：
// - 静态结构，利于 Tree Shaking
// - 异步加载
// - 浏览器和 Node.js 都支持

// === CommonJS ===
// counter.js
let count = 0
module.exports = {
  count,
  increment: () => count++
}

// main.js
const counter = require('./counter')
console.log(counter.count) // 0
counter.increment()
console.log(counter.count) // 0（值的拷贝，不会变）


// === ES Modules ===
// counter.js
export let count = 0
export const increment = () => count++

// main.js
import { count, increment } from './counter.js'
console.log(count) // 0
increment()
console.log(count) // 1（值的引用，会变）

// 传统方式（Webpack）
// 启动时就编译所有文件（1000+ 个文件）
app.js (500KB) ← 打包了所有模块

// Vite 方式
// 启动时不编译，浏览器请求哪个就编译哪个
main.js     ← 只编译入口文件
├─ App.vue  ← 浏览器请求时才编译
├─ Home.vue ← 浏览器请求时才编译
└─ About.vue ← 没请求，不编译

// 问题：lodash-es 有 600+ 个小文件
import { debounce } from 'lodash-es'

// 不预构建：浏览器要发 600+ 个请求 😰
GET /node_modules/lodash-es/debounce.js
GET /node_modules/lodash-es/delay.js
GET /node_modules/lodash-es/...
// 600+ 个请求

// Vite 预构建：合并成一个文件 ✅
GET /.vite/deps/lodash-es.js  // 只需 1 个请求

// lodash-es 有 600+ 个小模块
import { debounce } from 'lodash-es'

// 不预构建：浏览器会发起 600+ 个请求
// 预构建后：合并成一个文件，只需 1 个请求

// vite.config.ts
export default {
  optimizeDeps: {
    // 手动指定需要预构建的依赖
    include: [
      'vue',
      'vue-router',
      'pinia',
      'axios',
      'lodash-es',
    ],
    
    // 排除不需要预构建的依赖
    exclude: [
      'your-local-package',
    ],
    
    // esbuild 配置
    esbuildOptions: {
      target: 'es2020',
      plugins: [],
    },
    
    // 强制重新预构建
    force: true,
  },
}

// src/utils/math.ts
export const add = (a: number, b: number) => a + b

// 接受自身模块的更新
if (import.meta.hot) {
  import.meta.hot.accept((newModule) => {
    console.log('math 模块已更新', newModule)
  })
}

// Vite 插件自动处理
import { defineComponent } from 'vue'

export default defineComponent({
  setup() {
    // 组件内部状态会保留
    const count = ref(0)
    return { count }
  }
})

// rollup.config.js
import { defineConfig } from 'rollup'
import typescript from '@rollup/plugin-typescript'
import resolve from '@rollup/plugin-node-resolve'
import commonjs from '@rollup/plugin-commonjs'
import terser from '@rollup/plugin-terser'
import dts from 'rollup-plugin-dts'

export default defineConfig([
  // 主构建配置
  {
    // 入口文件
    input: 'src/index.ts',
    
    // 输出配置
    output: [
      // ESM 格式
      {
        file: 'dist/index.esm.js',
        format: 'esm',
        sourcemap: true,
      },
      // CommonJS 格式
      {
        file: 'dist/index.cjs.js',
        format: 'cjs',
        sourcemap: true,
        exports: 'named', // 导出模式
      },
      // UMD 格式（浏览器）
      {
        file: 'dist/index.umd.js',
        format: 'umd',
        name: 'MyLibrary', // 全局变量名
        sourcemap: true,
        globals: {
          // 外部依赖的全局变量映射
          vue: 'Vue',
          lodash: '_',
        },
      },
    ],
    
    // 外部依赖（不打包进产物）
    external: [
      'vue',
      'lodash',
      /^@vue\//,  // 正则匹配
    ],
    
    // 插件
    plugins: [
      // 解析 node_modules 中的模块
      resolve({
        extensions: ['.ts', '.js'],
        preferBuiltins: true,
      }),
      
      // 转换 CommonJS 模块为 ESM
      commonjs(),
      
      // TypeScript 支持
      typescript({
        tsconfig: './tsconfig.json',
        declaration: false, // 类型文件单独生成
      }),
      
      // 压缩
      terser({
        compress: {
          drop_console: true,
        },
      }),
    ],
    
    // Tree Shaking 配置
    treeshake: {
      moduleSideEffects: false,
      propertyReadSideEffects: false,
      unknownGlobalSideEffects: false,
    },
  },
  
  // 类型文件构建
  {
    input: 'src/index.ts',
    output: {
      file: 'dist/index.d.ts',
      format: 'esm',
    },
    plugins: [dts()],
  },
])

// utils.js
export const add = (a, b) => a + b
export const subtract = (a, b) => a - b
export const multiply = (a, b) => a * b

// main.js
import { add } from './utils.js'
console.log(add(1, 2))

// 打包后：multiply 和 subtract 会被删除

// utils.js
export const add = (a, b) => a + b

// 副作用：修改全局变量
window.__APP_VERSION__ = '1.0.0'

// 即使没用到 add，这段代码也会保留

// rollup-plugin-performance.js
export function performancePlugin() {
  return {
    name: 'rollup-plugin-performance',
    
    transform(code, id) {
      // 只处理 .js 和 .ts 文件
      if (!/\.(js|ts)$/.test(id)) return null
      
      // 正则匹配导出的函数
      const regex = /export (function|const|let|var) (\w+)/g
      let match
      const functions = []
      
      while ((match = regex.exec(code)) !== null) {
        functions.push(match[2])
      }
      
      if (functions.length === 0) return null
      
      // 生成包装代码
      const wrapperCode = functions.map(fnName => `
        const original_${fnName} = ${fnName}
        ${fnName} = function(...args) {
          const start = performance.now()
          const result = original_${fnName}.apply(this, args)
          const end = performance.now()
          console.log(\`[Performance] ${fnName} took \${end - start}ms\`)
          return result
        }
      `).join('\n')
      
      return {
        code: code + '\n' + wrapperCode,
        map: null,
      }
    },
  }
}