钩子故障排除

常见问题诊断

1. 钩子未触发

这是最常见的问题之一，通常有以下几个原因：

文件模式不匹配

症状：钩子从未执行，即使在预期的文件操作后也没有反应

诊断步骤：

检查清单:
  文件模式验证:
    - 确认文件模式是否正确匹配目标文件
    - 验证文件扩展名拼写
    - 检查路径分隔符（使用 / 而非 \）
    - 确认通配符使用正确

  测试方法:
    - 创建简单的测试文件
    - 使用在线 glob 模式测试器验证
    - 检查文件是否在排除列表中

常见错误和修正：

# ❌ 错误的模式
错误示例:
  - "*.js"           # 只匹配根目录的 .js 文件
  - "src\**\*.ts"    # 使用了错误的路径分隔符
  - "**/*.tsx?"      # 错误的通配符语法

# ✅ 正确的模式
正确示例:
  - "**/*.js"        # 匹配所有目录的 .js 文件
  - "src/**/*.ts"    # 正确的路径分隔符
  - "**/*.{ts,tsx}"  # 正确的多扩展名匹配

钩子未启用

症状：钩子配置存在但从未执行

解决方案：

  1. 打开代理钩子面板
  2. 检查钩子名称旁的状态指示器
  3. 点击眼睛图标启用钩子
  4. 确认状态变为”已启用”

事件类型错误

症状：钩子在错误的时机触发或从不触发

常见事件类型问题：

事件类型验证:
  onSave: 
    触发时机: 文件保存时
    注意事项: 自动保存可能不触发
  
  onCreate:
    触发时机: 新文件创建时
    注意事项: 复制文件可能不算创建
  
  preCommit:
    触发时机: Git 提交前
    注意事项: 需要在 Git 仓库中
  
  manual:
    触发时机: 手动执行
    注意事项: 需要通过界面手动启动

2. 钩子行为异常

执行结果不符合预期

症状：钩子执行了，但结果与预期不符

诊断方法：

行为分析步骤:
  1. 指令审查:
     - 检查指令是否清晰明确
     - 确认每个步骤都有具体描述
     - 验证指令逻辑的合理性
  
  2. 上下文检查:
     - 确认文件内容符合预期
     - 检查相关依赖是否存在
     - 验证环境配置是否正确
  
  3. 冲突检测:
     - 查找可能冲突的其他钩子
     - 检查执行顺序问题
     - 确认没有相互干扰

指令优化示例：

# ❌ 模糊的指令
模糊指令:
  "检查代码质量"

# ✅ 具体的指令
具体指令: |
  执行以下代码质量检查：
  1. 运行 ESLint 检查语法错误
  2. 验证代码格式是否符合 Prettier 规范
  3. 检查是否存在未使用的变量
  4. 确认函数和变量命名符合项目约定
  5. 验证是否包含必要的类型注解

钩子冲突

症状：多个钩子同时执行导致意外结果

解决策略：

冲突解决方案:
  识别冲突:
    - 列出所有相同触发条件的钩子
    - 分析文件模式的重叠部分
    - 检查执行顺序和优先级
  
  解决方法:
    - 调整文件模式避免重叠
    - 设置钩子执行优先级
    - 合并相似功能的钩子
    - 使用条件逻辑分离职责

3. 性能问题

钩子执行缓慢

症状：钩子执行时间过长，影响开发体验

性能优化策略：

性能诊断:
  执行时间分析:
    - 记录每次执行的耗时
    - 识别性能瓶颈环节
    - 分析资源使用情况
  
  优化方法:
    文件模式优化:
      - 使用更精确的匹配模式
      - 排除不必要的目录
      - 限制文件大小范围
    
    指令简化:
      - 减少复杂的处理逻辑
      - 拆分大型任务为小任务
      - 避免重复计算
    
    缓存策略:
      - 缓存计算结果
      - 避免重复的文件读取
      - 使用增量处理方式

性能监控示例：

性能监控配置:
  execution_tracking:
    max_execution_time: 10s
    performance_alerts:
      warning_threshold: 5s
      critical_threshold: 15s
    
  optimization_triggers:
    - 连续3次执行超过警告阈值
    - 任意单次执行超过关键阈值
    - 用户投诉性能问题

频繁触发问题

症状：钩子过于频繁执行，消耗系统资源

解决方案：

频率控制:
  触发限制:
    - 设置最小触发间隔
    - 使用防抖延迟机制
    - 批量处理相关变更
  
  智能过滤:
    - 忽略临时文件变更
    - 跳过自动生成的文件
    - 过滤无关的文件类型

高级调试技术

日志分析

启用详细日志

日志配置:
  log_level: debug
  log_categories:
    - hook_execution
    - file_matching
    - performance_metrics
    - error_details
  
  log_output:
    console: true
    file: .kiro/logs/hooks.log
    structured: true

日志分析示例

# 日志记录示例
log_entries:
  - timestamp: "2025-07-21T10:30:15Z"
    level: "INFO"
    message: "Hook triggered: code_formatter"
    metadata:
      file: "src/components/Button.jsx"
      trigger: "onSave"
      execution_time: "1.2s"
  
  - timestamp: "2025-07-21T10:30:16Z"
    level: "ERROR"
    message: "Hook execution failed"
    metadata:
      hook: "test_generator"
      error: "FileNotFoundError: test file template not found"
      file: "src/utils/helpers.js"

测试环境设置

隔离测试

测试环境配置:
  test_workspace:
    location: ".kiro/test-workspace"
    isolation: true
    cleanup_after_test: true
  
  test_scenarios:
    - empty_files
    - malformed_syntax
    - large_files
    - unicode_content
    - binary_files

模拟测试

# 创建测试用例
test_cases:
  basic_functionality:
    files:
      - name: "test.js"
        content: "console.log('hello');"
        expected_result: "格式化并添加分号"
  
  edge_cases:
    files:
      - name: "empty.js"
        content: ""
        expected_result: "跳过处理空文件"
      
      - name: "syntax-error.js"
        content: "const a = ;"
        expected_result: "报告语法错误"

错误处理和恢复

自动恢复机制

错误恢复策略:
  retry_logic:
    max_attempts: 3
    backoff_strategy: exponential
    retry_conditions:
      - temporary_file_lock
      - network_timeout
      - resource_busy
  
  fallback_actions:
    - 记录详细错误信息
    - 通知用户失败原因
    - 提供手动重试选项
    - 回滚部分更改

错误分类和处理

错误类型处理:
  critical_errors:
    - file_corruption
    - system_permission_denied
    - out_of_memory
    action: 停止执行并报告
  
  recoverable_errors:
    - temporary_file_lock
    - network_interruption
    - tool_not_found
    action: 重试执行
  
  warning_errors:
    - deprecated_syntax
    - performance_concern
    - best_practice_violation
    action: 继续执行但记录警告

维护和预防

定期健康检查

钩子审计清单

月度审计清单:
  配置审查:
    - 检查钩子配置的时效性
    - 验证文件模式的准确性
    - 确认指令的清晰度
  
  性能评估:
    - 分析执行时间趋势
    - 评估资源使用情况
    - 识别性能下降的钩子
  
  功能验证:
    - 测试钩子的预期功能
    - 验证错误处理机制
    - 确认输出质量

自动化监控

监控指标:
  success_rate:
    threshold: ">95%"
    alert_on_decline: true
  
  execution_time:
    average_threshold: "<5s"
    max_threshold: "<30s"
  
  error_frequency:
    max_errors_per_day: 10
    consecutive_failures: 3

最佳实践回顾

配置管理

配置最佳实践:
  版本控制:
    - 将钩子配置纳入版本控制
    - 记录配置变更历史
    - 维护配置文档
  
  环境管理:
    - 区分开发和生产环境配置
    - 使用环境特定的设置
    - 测试配置变更影响
  
  团队协作:
    - 建立配置变更审批流程
    - 共享钩子配置模板
    - 定期团队配置审查

升级和迁移

钩子升级策略

升级计划:
  准备阶段:
    - 备份当前钩子配置
    - 分析新版本的变更
    - 评估兼容性影响
  
  测试阶段:
    - 在测试环境验证升级
    - 运行完整的测试套件
    - 验证性能表现
  
  部署阶段:
    - 分阶段推出升级
    - 监控升级后的表现
    - 准备回滚计划

配置迁移

迁移检查清单:
  兼容性验证:
    - 检查废弃的配置选项
    - 验证新的必需参数
    - 测试向后兼容性
  
  功能验证:
    - 确认所有钩子正常工作
    - 验证性能没有退化
    - 检查错误处理机制

寻求帮助

社区资源

  • 查阅官方文档的故障排除指南：/docs/reference/troubleshooting
  • 参与 Kiro 社区讨论
  • 查看 GitHub Issues 中的类似问题
  • 参考团队知识库和最佳实践

报告问题

提交问题时请包含：

  • 钩子配置详情
  • 错误日志和截图
  • 重现步骤
  • 环境信息（操作系统、Kiro 版本等）
  • 预期行为描述

页面最后更新：2025年7月21日