前端技术债治理的年度复盘从积重难返到有序偿还的系统化方法技术债是每个长期维护的前端项目都无法回避的话题。这一年的治理过程从一个濒临失控的中型项目起步逐步建立了一套可复用的治理框架。复盘的意义不是展示成果而是沉淀那些回头看很简单、当时没想到的方法论教训。一、治理前的状态年初盘点时项目面临一个典型的技术债雪球代码层面。3.2万行TypeScript代码中绕过strict: true的// ts-ignore有47处any类型847处。核心业务逻辑分散在12个超过500行的巨型组件中圈复杂度最高的函数达到38。依赖层面。package.json中有11个已废弃的npm包、3个不同版本的momentdependencies和devDependencies中存在版本冲突。测试层面。测试覆盖率21%但大量测试是渲染不出错就行的快照测试几乎不具备回归保护能力。二、治理策略先止血后拆弹再还债技术债治理最忌讳全面开战。同时修复所有问题意味着同时引入所有风险。一年的实践验证了三阶段策略的有效性。第一阶段止血第1个月。停止新增技术债。这一阶段不做修复只做规则堵漏。在CI中加入自动化检查禁止新增any类型、禁止合并超过500行的组件、禁止引入已废弃的依赖包。第二阶段拆弹第2-4月。处理高风险技术债。优先级排序不是按最容易修而是按修坏了影响最小。封装隔离风险区域的API为核心业务路径补上集成测试。第三阶段还债第5-12月。系统性地偿还存量技术债。按模块逐个还清每次只选择一个模块避免上下文切换。// 技术债自动化拦截CI中的代码质量门禁 import { execSync } from node:child_process; import fs from node:fs; import path from node:path; interface DebtRule { name: string; description: string; check: () DebtCheckResult; severity: block | warn; } interface DebtCheckResult { passed: boolean; message: string; baseline: number; // 当前存量 diff: number; // 本次PR新增量正数为新增债 } // 规则1禁止新增 any 类型 const anyTypeRule: DebtRule { name: no-new-any, description: PR中禁止新增any类型声明, severity: block, check(): DebtCheckResult { // 对比PR分支和main分支的any数量 try { const mainAny countAnyInBranch(origin/main); const prAny countAnyInBranch(HEAD); const diff prAny - mainAny; return { passed: diff 0, message: diff 0 ? 新增了 ${diff} 处any类型声明请使用具体类型替代 : any类型数量不变或减少(-${Math.abs(diff)}处), baseline: mainAny, diff }; } catch (error) { return { passed: true, message: any类型检查跳过分支获取失败, baseline: 0, diff: 0 }; } } }; // 规则2禁止超过500行的组件文件 const fileSizeRule: DebtRule { name: max-file-lines, description: 组件文件不得超过500行, severity: block, check(): DebtCheckResult { // 获取PR新增或修改的组件文件 const changedFiles execSync( git diff --name-only --diff-filterAM origin/main...HEAD, { encoding: utf-8 } ).split(\n).filter(f f.match(/\.(tsx|jsx)$/)); const violations: string[] []; for (const file of changedFiles) { if (!fs.existsSync(file)) continue; const lines fs.readFileSync(file, utf-8).split(\n).length; if (lines 500) { violations.push( ${file}: ${lines}行 (限制500行)); } } return { passed: violations.length 0, message: violations.length 0 ? 以下文件超过行数限制:\n${violations.join(\n)} : 所有组件文件行数合规, baseline: 0, diff: violations.length }; } }; // 规则3禁止引入废弃依赖 const deprecatedDepRule: DebtRule { name: no-deprecated-deps, description: 禁止安装已知的废弃npm包, severity: block, // 已知废弃/不推荐使用的包列表 deprecatedPackages: [ moment, request, left-pad, core-js2, babel-eslint, tslint, types/tslint ], check(): DebtCheckResult { // 检查新增的依赖 const mainPkg JSON.parse( execSync(git show origin/main:package.json, { encoding: utf-8 }) ); const prPkg JSON.parse(fs.readFileSync(package.json, utf-8)); const mainDeps new Set([ ...Object.keys(mainPkg.dependencies || {}), ...Object.keys(mainPkg.devDependencies || {}) ]); const prDeps [ ...Object.keys(prPkg.dependencies || {}), ...Object.keys(prPkg.devDependencies || {}) ]; const newDeps prDeps.filter(d !mainDeps.has(d)); const deprecatedFound newDeps.filter(d this.deprecatedPackages.some(dp d dp || d.startsWith(dp )) ); return { passed: deprecatedFound.length 0, message: deprecatedFound.length 0 ? 新增了废弃依赖: ${deprecatedFound.join(, )} : 依赖检查通过, baseline: 0, diff: deprecatedFound.length }; } }; // 辅助函数统计分支中的any数量 function countAnyInBranch(ref: string): number { try { const output execSync( git grep -c : any ${ref} -- *.ts *.tsx | grep -v node_modules | grep -v .d.ts, { encoding: utf-8, stdio: [pipe, pipe, pipe] } ); return output .split(\n) .filter(line line.includes(:)) .reduce((sum, line) { const count parseInt(line.split(:).pop() || 0, 10); return sum (isNaN(count) ? 0 : count); }, 0); } catch { return 0; } } // 导出规则集 export const debtGateRules: DebtRule[] [ anyTypeRule, fileSizeRule, deprecatedDepRule ];三、关键教训那些做错的和做对的做错的一开始想全量修复。第一周的冲动是将所有any类型一次性改成具体类型。结果发现很多any背后是未文档化的隐式接口契约强行改类型导致3个核心功能回归。教训类型债务必须配合接口文档化先理解意图再修复。做错的测试先行不足。大规模重构前没有补足测试覆盖。重构进行到一半时发现无法验证功能是否受损被迫暂停重构补充测试。教训偿还技术债的顺序应该是先加测试 → 再还债 → 最后重构。做对的自动化门禁机制。每个还清的债如禁止新增any、文件不超过500行立即加入CI门禁。这确保了一个模块还清后不会再次积债。做对的量化追踪。用每周的技术债仪表盘展示各项指标的走势。可视化的下降趋势本身就对团队有激励作用——看到数字在下降还债就有了动力。四、下半年路线图基于当前状态和年内目标下半年的路线图分为三个重点。Q3: 提升测试质量7月-9月。将测试策略从快照测试为主转向集成测试为主。围绕5条核心用户路径补齐E2E测试。目标核心路径覆盖率达到80%。Q4: 模块化重构10月-12月。将剩余的4个巨型组件当前在500-800行范围拆分为可独立测试的模块。引入模块边界规范用ESLint规则强制模块间依赖方向。持续依赖现代化。评估并迁移Vite 6 React 19目前使用Vite 5 React 18。RN 19的并发特性有望减少现有的大量手动性能优化代码。五、总结技术债治理不是一次性的大扫除而是建立一套只还不借的机制。一年实践的核心认知治理的本质是改变习惯。自动化门禁改的是在PR中写any很方便的习惯。如果只改代码不改流程三个月后技术债全面回归。先止血比先还债重要得多。停止新增技术债的ROI远高于修复存量。一个no-new-any的CI检查价值超过改100个已有的any类型。量化是治理的燃料。每周更新的技术债仪表盘让还债从抽象口号变成了可追踪的数字游戏。看到any从847降到312团队就有了继续下去的信心。下半年最大的挑战是重构与业务需求的平衡——如何在保障日常迭代的同时持续推进Q3-Q4的技术债清偿计划。这需要产品和技术在排期上有更大的共识。代码示例基于TypeScript 5.6 ESLint 9 Node.js 22。CI环境为GitLab CI。