构建排障

构建问题是开发中常见的障碍。本指南介绍如何使用 Claude Code 快速诊断和解决构建问题。

常见构建问题

依赖问题

依赖相关的构建错误：

构建失败，错误信息：
Module not found: Can't resolve 'lodash'

帮我：
1. 诊断问题原因
2. 检查 package.json
3. 提供解决方案

配置问题

配置错误导致的构建失败：

Webpack 构建失败：
Invalid configuration object

分析：
@webpack.config.js

找出：
- 配置错误
- 正确的配置方式
- 最佳实践

版本冲突

依赖版本冲突：

构建警告：
peer dependency warning

分析依赖树：
- 找出冲突的包
- 确定兼容版本
- 提供解决方案

系统化排障流程

第一步：收集信息

收集完整的错误信息：

构建失败，收集诊断信息：

需要：
1. 完整的错误堆栈
2. 构建配置文件
3. package.json
4. 环境信息（Node 版本等）
5. 最近的更改

输出诊断报告

第二步：重现问题

确保能够重现问题：

尝试重现构建问题：

步骤：
1. 清理缓存（npm cache clean）
2. 删除 node_modules
3. 重新安装依赖
4. 重新构建

记录每步的结果

第三步：隔离问题

缩小问题范围：

隔离构建问题：

测试：
1. 是否只在特定环境出现
2. 是否与特定文件相关
3. 是否与特定依赖相关
4. 最近哪次提交引入的

输出问题范围

第四步：分析根因

找出问题的根本原因：

分析构建失败的根本原因：

错误信息：
[粘贴错误]

分析：
- 错误的直接原因
- 为什么会发生
- 相关的配置或代码
- 类似问题的解决方案

第五步：实施修复

应用解决方案：

修复构建问题：

问题：[描述]
根因：[分析结果]

修复方案：
1. 具体步骤
2. 需要修改的文件
3. 验证方法

实施修复并验证

特定工具的排障

Webpack 排障

诊断 Webpack 构建问题：

Webpack 构建失败排障：

错误：[错误信息]

检查：
1. webpack.config.js 配置
2. loader 配置
3. plugin 配置
4. 入口和输出配置
5. resolve 配置

提供：
- 问题诊断
- 修复方案
- 配置优化建议

Vite 排障

诊断 Vite 构建问题：

Vite 构建失败排障：

错误：[错误信息]

检查：
1. vite.config.js
2. 插件配置
3. 依赖预构建
4. 环境变量
5. 路径别名

提供解决方案

TypeScript 排障

诊断 TypeScript 编译问题：

TypeScript 编译错误排障：

错误：[错误信息]

检查：
1. tsconfig.json 配置
2. 类型定义
3. 模块解析
4. 编译选项
5. 类型兼容性

提供修复方案

Babel 排障

诊断 Babel 转译问题：

Babel 转译失败排障：

错误：[错误信息]

检查：
1. .babelrc 或 babel.config.js
2. preset 配置
3. plugin 配置
4. 目标环境配置
5. 源码兼容性

提供解决方案

性能问题排障

构建速度慢

优化构建速度：

构建速度很慢，进行性能分析：

当前情况：
- 构建时间：5 分钟
- 项目规模：中等

分析：
1. 使用构建分析工具
2. 识别慢的步骤
3. 找出优化机会

提供：
- 性能分析报告
- 优化建议
- 预期改进效果

内存问题

解决构建内存问题：

构建时内存溢出：

错误：JavaScript heap out of memory

解决：
1. 增加 Node 内存限制
2. 优化构建配置
3. 分析内存使用
4. 减少并发任务

提供具体方案

打包体积大

优化打包体积：

打包体积过大排查：

当前：bundle.js 5MB

分析：
1. 使用 bundle analyzer
2. 识别大的依赖
3. 找出重复的代码
4. 检查未使用的代码

提供：
- 体积分析报告
- 优化方案
- 预期减小幅度

环境相关问题

跨平台问题

解决跨平台构建问题：

Windows 上构建失败，Mac 上正常：

错误：[错误信息]

检查：
1. 路径分隔符
2. 文件名大小写
3. 行尾符（CRLF vs LF）
4. 环境变量
5. 脚本兼容性

提供跨平台解决方案

Node 版本问题

解决 Node 版本兼容问题：

不同 Node 版本构建结果不同：

当前版本：Node 16
目标版本：Node 18

检查：
1. package.json engines 字段
2. 依赖的 Node 版本要求
3. 使用的 Node API
4. 构建工具兼容性

提供版本兼容方案

CI/CD 环境问题

解决 CI/CD 构建问题：

本地构建成功，CI 失败：

CI 错误：[错误信息]

对比：
1. 环境变量
2. Node 版本
3. 依赖版本
4. 构建脚本
5. 缓存策略

找出差异并修复

依赖管理问题

锁文件冲突

解决锁文件问题：

package-lock.json 冲突：

问题：
- 合并冲突
- 版本不一致

解决：
1. 理解锁文件的作用
2. 正确解决冲突
3. 验证依赖完整性
4. 更新锁文件

提供详细步骤

幽灵依赖

识别和解决幽灵依赖：

检查幽灵依赖：

分析：
- 代码中使用但未声明的依赖
- 通过其他包间接引入的依赖

解决：
1. 识别所有幽灵依赖
2. 添加到 package.json
3. 验证构建

提供完整列表和修复

依赖安全问题

解决依赖安全漏洞：

npm audit 发现安全漏洞：

漏洞：[列表]

处理：
1. 评估漏洞严重性
2. 检查是否有修复版本
3. 更新依赖
4. 如无法更新，寻找替代方案

提供修复计划

缓存问题

清理缓存

清理各种缓存：

构建结果不正确，可能是缓存问题：

清理：
1. npm/yarn/pnpm 缓存
2. 构建工具缓存（Webpack/Vite）
3. TypeScript 缓存
4. IDE 缓存
5. node_modules

提供清理脚本

缓存策略

优化缓存策略：

优化构建缓存：

目标：
- 加快构建速度
- 确保缓存正确性

配置：
1. 依赖缓存
2. 构建缓存
3. 缓存失效策略
4. CI/CD 缓存

提供配置方案

调试技巧

详细日志

启用详细日志：

启用构建详细日志：

工具：
- npm: npm run build --verbose
- webpack: --progress --profile
- vite: --debug

分析日志找出问题

逐步构建

逐步排查问题：

逐步构建排查：

步骤：
1. 注释掉所有入口
2. 逐个启用
3. 找出导致失败的文件
4. 分析该文件的问题

记录每步结果

最小复现

创建最小复现案例：

创建最小复现案例：

目标：
- 隔离问题
- 便于调试
- 便于报告 bug

步骤：
1. 创建新项目
2. 只包含必要代码
3. 复现问题
4. 逐步简化

输出最小案例

常见错误解决

Module not found

错误：Module not found: Can't resolve 'xxx'

可能原因：
1. 依赖未安装
2. 路径错误
3. 别名配置错误
4. 文件扩展名问题

解决方案：
1. 检查 package.json
2. 验证文件路径
3. 检查 resolve 配置
4. 安装缺失的依赖

Syntax Error

错误：SyntaxError: Unexpected token

可能原因：
1. 使用了不支持的语法
2. Babel 配置不正确
3. 文件未被正确处理
4. 源码版本问题

解决方案：
1. 检查目标环境
2. 配置正确的 preset
3. 添加必要的 plugin
4. 检查 loader 配置

Out of Memory

错误：JavaScript heap out of memory

解决方案：
1. 增加内存限制
   NODE_OPTIONS=--max-old-space-size=4096

2. 优化构建配置
   - 减少并发
   - 使用增量构建
   - 优化 loader

3. 分析内存使用
   - 使用 heap snapshot
   - 找出内存泄漏

预防措施

构建检查清单

建立构建检查清单：

## 构建前检查

- [ ] 依赖已安装
- [ ] 配置文件正确
- [ ] 环境变量已设置
- [ ] Node 版本正确
- [ ] 缓存已清理（如需要）

## 构建后检查

- [ ] 构建成功
- [ ] 输出文件正确
- [ ] 体积合理
- [ ] 功能正常
- [ ] 性能达标

持续监控

监控构建健康度：

建立构建监控：

指标：
- 构建时间
- 构建成功率
- 打包体积
- 依赖安全性

告警：
- 构建时间超过阈值
- 构建失败
- 体积增长过大
- 发现安全漏洞

输出监控仪表板

文档化

记录常见问题和解决方案：

创建构建问题知识库：

内容：
- 常见问题
- 解决方案
- 预防措施
- 最佳实践

格式：FAQ 或问题-解决方案对
位置：docs/troubleshooting/build.md

工具推荐

诊断工具

推荐的构建诊断工具：

分析工具：
- webpack-bundle-analyzer
- source-map-explorer
- speed-measure-webpack-plugin

调试工具：
- node --inspect
- Chrome DevTools
- VS Code debugger

监控工具：
- build-tracker
- bundlesize

自动化脚本

创建构建排障脚本：

功能：
1. 环境检查
2. 依赖验证
3. 配置验证
4. 缓存清理
5. 诊断报告

脚本：scripts/diagnose-build.sh

最佳实践

1. 保持依赖更新
2. 使用锁文件
3. 配置合理的缓存
4. 监控构建性能
5. 记录构建问题
6. 定期清理和优化
7. 使用 CI/CD 验证
8. 建立排障流程

总结

有效的构建排障需要：

• 系统化的排障流程
• 对构建工具的深入理解
• 丰富的问题解决经验
• 完善的监控和预防机制

通过 Claude Code 的帮助，你可以更快速地诊断和解决构建问题，保持开发流程的顺畅。