mcpField
M
magento-issue-debugger

magento-issue-debugger

github.com/maxnorm开发31256 次安装40 周前更新
代码仓库

关于 magento-issue-debugger

面向 Magento 2 开发与运维人员的故障排查技能，指导从复现问题、收集日志到分析根因和验证修复的系统流程。覆盖性能、功能、集成及系统层问题。

主要功能

  1. 01制定复现步骤并记录环境
  2. 02收集日志、配置与性能数据
  3. 03分析代码、数据库及模块
  4. 04隔离测试并定位根因
  5. 05规划修复、测试与回滚

适用场景

  1. 01排查生产环境错误
  2. 02分析页面或数据库性能问题
  3. 03定位缓存、索引或模块冲突
  4. 04调查支付、API 或系统故障

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/maxnorm/magento2-agent-skills --skill magento-issue-debugger

安装后在 Claude Code 中输入/magento-issue-debugger确认已加载。

详细介绍

Magento 2 问题调试器

专家级专员，负责系统地调查、诊断和解决 Magento 技术栈各层中的复杂技术问题。

适用场景

  • 调试生产环境问题
  • 调查 Bug 和错误
  • 分析性能问题
  • 解决系统故障
  • 排查集成问题
  • 诊断缓存或索引问题

调试方法

系统化调查
  • 问题评估：确定可稳定复现问题的步骤
  • 环境文档记录：整理系统配置和环境详情
  • 影响分析：确定影响范围、频率和业务影响
  • 时间线分析：确定问题何时开始以及期间发生了哪些变化
  • 隔离测试：禁用模块和功能，以隔离问题
根因分析
  • 假设测试：系统地提出并验证假设
  • 数据收集：收集日志、配置和性能指标
  • 代码分析：检查近期代码变更和相关模块
  • 数据库调查：检查数据损坏或迁移问题
  • 深入排查：深入查找根本原因，而不是只处理症状

问题调查流程

1. 问题评估
  • 问题复现：确定可稳定复现问题的步骤
  • 环境文档记录：整理系统配置
  • 影响分析：确定影响范围和业务影响
  • 时间线分析：确定问题何时开始
  • 用户影响：了解问题对不同类型用户的影响
2. 数据收集
  • 日志收集：收集所有系统组件的相关日志
    • Magento 日志：var/log/
    • PHP 错误日志
    • Web 服务器日志（Apache/Nginx）
    • 数据库慢查询日志
  • 配置检查：检查模块配置和系统设置
  • 代码分析：检查近期代码变更和相关模块
  • 数据库调查：检查数据损坏或迁移问题
  • 性能指标：收集耗时和资源使用数据
3. 系统化调试
  • 调试模式：启用 Magento 调试模式，以获取详细错误报告 
    bin/magento deploy:mode:set developer
  • Xdebug 集成：使用单步调试排查复杂逻辑问题
  • 性能分析工具：使用 Blackfire、XHProf 或类似工具排查性能问题
  • 数据库调试：启用查询日志并分析数据库交互
  • 隔离测试：禁用模块以隔离问题
4. 实施解决方案
  • 开发修复方案：根据根因分析实施适当的修复
  • 测试策略：制定全面的测试计划以进行验证
  • 回滚计划：为生产环境修复准备回滚流程
  • 文档记录：记录调查结果、解决方案和预防策略
  • 监控设置：实施监控，防止问题再次发生

常见问题类别

性能问题
  • 页面加载缓慢：识别前端和后端处理中的瓶颈
  • 数据库性能：优化查询、索引和数据库配置
  • 内存问题：排查内存泄漏和高内存使用问题
  • 缓存问题：解决缓存失效和缓存预热问题
  • 前端性能：排查 JavaScript 错误和 CSS 渲染问题
功能缺陷
  • 结账问题：调试支付处理、配送和下单流程
  • 商品展示：解决目录、搜索和商品页面问题
  • 管理面板问题：修复后台功能和配置问题
  • 扩展冲突：识别并解决模块兼容性问题
  • API 问题：调试 REST 和 GraphQL API 端点
系统级问题
  • 安装问题：解决设置和升级问题
  • 配置错误：修复系统和模块配置问题
  • 文件权限问题：解决文件系统和目录权限问题
  • Cron 作业失败：调试计划任务执行问题
  • 电子邮件问题：解决电子邮件发送和模板问题
安全问题
  • 访问控制：调试权限和 ACL 问题
  • 身份验证问题：解决登录和会话问题
  • CSRF 失败：调试表单密钥验证问题
  • SQL 注入：识别并修复存在漏洞的查询
  • XSS 漏洞：修复输出转义问题

调试工具和技术

日志分析
  • Magento 日志：var/log/exception.log、var/log/system.log
  • PHP 错误日志：检查 PHP-FPM 或 Apache 错误日志
  • Web 服务器日志：分析 Apache/Nginx 访问日志和错误日志
  • 数据库日志：检查慢查询日志和数据库错误
  • 自定义日志记录：针对特定问题实现自定义日志记录
性能分析
  • Blackfire：性能分析和优化
  • XHProf：PHP 性能分析工具
  • New Relic：APM 监控
  • 数据库性能分析：启用查询日志记录
  • 前端性能分析：使用浏览器 DevTools 进行性能分析
调试命令
# Enable developer mode
bin/magento deploy:mode:set developer

# Clear cache
bin/magento cache:clean
bin/magento cache:flush

# Reindex
bin/magento indexer:reindex

# Check compilation
bin/magento setup:di:compile

# Check static content
bin/magento setup:static-content:deploy

# Check database
bin/magento setup:db:status
代码调试
  • Xdebug：单步调试
  • var_dump/die：快速调试（上线前请移除）
  • Magento Logger：使用 \Psr\Log\LoggerInterface 记录日志
  • 异常处理：妥善捕获和记录异常
  • 错误报告：配置错误报告级别

最佳实践

预防
  • 全面测试：编写单元测试、集成测试和功能测试
  • 代码审查：定期审查代码，及早发现问题
  • 监控：实施监控和告警
  • 日志记录：制定全面的日志记录策略
  • 文档：维护清晰的文档
问题解决
  • 根本原因：始终修复根本原因，而非表面症状
  • 测试：部署前彻底测试修复内容
  • 文档：记录问题和解决方案
  • 沟通：与相关方沟通
  • 监控：修复部署后进行监控

参考资料

通过系统化排查，确定根本原因并实施持久有效的解决方案。

评论

支持 Markdown