第 10 章 错误处理与调试

/usr/local/lib/node_modules/repox/dist/index.js:1247
  const items = data.map(fn)
                     ^
TypeError: Cannot read properties of undefined (reading 'map')
    at processResult (/usr/local/lib/node_modules/repox/dist/index.js:1247:22)
    at async run (/usr/local/lib/node_modules/repox/dist/index.js:892:5)

✖ 未找到配置文件 .repoxrc
  提示: 运行 repox init 创建默认配置

Error: ENOENT: no such file or directory, open '/Users/dev/project/.repoxrc'
    at Object.openSync (node:fs:603:3)
    at Object.readFileSync (node:fs:471:35)
    ...

// src/core/error.ts
export class UserError extends Error {
  constructor(
    message: string,
    public hint?: string,
  ) {
    super(message)
    this.name = 'UserError'
  }
}

if (!apiKey) {
  throw new UserError(
    '未配置 AI API Key',
    '运行 repox auth 或设置环境变量 REPOX_AI_API_KEY'
  )
}

// src/core/error.ts
export class NetworkError extends Error {
  constructor(
    message: string,
    public statusCode?: number,
    public url?: string,
  ) {
    super(message)
    this.name = 'NetworkError'
  }
}

if (!response.ok) {
  const errorBody = await response.text().catch(() => '')
  throw new NetworkError(
    `请求失败: ${response.status} ${response.statusText}${errorBody ? ` - ${errorBody}` : ''}`,
    response.status,
    url,
  )
}

// src/core/error.ts
export function handleError(error: unknown): never {
  if (error instanceof UserError) {
    console.error(chalk.red('✖'), error.message)
    if (error.hint) {
      console.error(chalk.gray('  提示:'), error.hint)
    }
    process.exit(ExitCode.USAGE_ERROR)
  } else if (error instanceof NetworkError) {
    console.error(chalk.red('✖'), `网络请求失败: ${error.message}`)
    if (error.url) {
      console.error(chalk.gray('  请求地址:'), error.url)
    }
    if (error.statusCode) {
      console.error(chalk.gray('  状态码:'), error.statusCode)
    }
    process.exit(ExitCode.GENERAL_ERROR)
  } else if (error instanceof Error) {
    console.error(chalk.red('✖'), `发生意外错误: ${error.message}`)
    if (getLogLevel() === 'debug') {
      console.error(chalk.gray(error.stack ?? ''))
    } else {
      console.error(chalk.gray('  使用 --debug 查看完整错误信息'))
    }
    process.exit(ExitCode.GENERAL_ERROR)
  } else {
    console.error(chalk.red('✖'), '发生未知错误')
    process.exit(ExitCode.GENERAL_ERROR)
  }
}

repox scan --format json > report.json && echo "扫描成功" || echo "扫描失败"

// src/core/error.ts
export const ExitCode = {
  SUCCESS: 0,        // 一切正常
  GENERAL_ERROR: 1,  // 一般性错误（网络、内部异常）
  USAGE_ERROR: 2,    // 使用方式错误（参数、配置）
  NOT_FOUND: 127,    // 命令或资源未找到
  INTERRUPTED: 130,  // 用户中断（Ctrl+C）
} as const

#!/usr/bin/env node
import { run } from './cli.js'
 
// 优雅处理 Ctrl+C
process.on('SIGINT', () => {
  console.log('\n已中断')
  process.exit(130)
})
 
// 未捕获异常的兜底
process.on('uncaughtException', (error) => {
  console.error('发生意外错误:', error.message)
  if (process.env.DEBUG) {
    console.error(error.stack)
  }
  process.exit(1)
})
 
run()

process.on('SIGTERM', () => {
  // 关闭数据库连接、保存状态等
  cleanup()
  process.exit(0) // SIGTERM 是正常终止请求，返回 0
})

let cleanupFns: (() => void)[] = []
 
export function onCleanup(fn: () => void) {
  cleanupFns.push(fn)
}
 
process.on('SIGINT', () => {
  cleanupFns.forEach(fn => {
    try { fn() } catch { /* 清理时不抛错 */ }
  })
  console.log('\n已中断')
  process.exit(130)
})

const spinner = ora('正在分析...').start()
onCleanup(() => spinner.stop()) // 确保 Ctrl+C 时 spinner 停止

// src/cli.ts
program.hook('preAction', (thisCommand) => {
  const opts = thisCommand.opts()
  if (opts.debug) {
    setLogLevel('debug')
  } else if (opts.verbose) {
    setLogLevel('verbose')
  } else if (opts.quiet) {
    setLogLevel('quiet')
  }
})

export type LogLevel = 'quiet' | 'normal' | 'verbose' | 'debug'
 
const LEVEL_PRIORITY: Record<LogLevel, number> = {
  quiet: 0,
  normal: 1,
  verbose: 2,
  debug: 3,
}
 
function shouldLog(level: LogLevel): boolean {
  return LEVEL_PRIORITY[currentLevel] >= LEVEL_PRIORITY[level]
}

process.on('uncaughtException', (error) => {
  console.error('发生意外错误:', error.message)
  if (process.env.DEBUG) {
    console.error(error.stack)
  }
  process.exit(1)
})

$ repox scan --debug
🔍 日志级别: debug
🔍 工作目录: /Users/dev/my-project
🔍 配置来源: /Users/dev/my-project/.repoxrc
🔍 扫描路径: /Users/dev/my-project
🔍 检测到 package.json
🔍 包管理器: pnpm (pnpm-lock.yaml)
🔍 检测到框架: react, next
ℹ 正在扫描...
✔ 扫描完成

{
  "version": "0.2.0",
  "configurations": [{
    "name": "Debug repox",
    "type": "node",
    "request": "launch",
    "runtimeExecutable": "npx",
    "runtimeArgs": ["tsx", "src/index.ts", "scan", "--format", "json"],
    "console": "integratedTerminal",
    "skipFiles": ["<node_internals>/**"]
  }]
}

node --inspect -r tsx/esm src/index.ts doctor

// fallback-channel.ts（简化版）
async connect() {
  if (isConnected) return;  // 幂等：重复调用不会出错
 
  const eventDispatcher = new lark.EventDispatcher({});
  eventDispatcher.register({
    "im.message.receive_v1": async (eventData: unknown) => {
      try {
        await handleEvent(eventData, options, client);
      } catch (err) {
        log("ERROR", "fallback_message_error", { error: String(err) });
      }
    },
  });
 
  wsClient = new lark.WSClient({ /* ... */ });
  await wsClient.start({ eventDispatcher });
  isConnected = true;
  log("INFO", "Fallback channel connected");
},

function log(level: string, msg: string, meta?: Record<string, unknown>) {
  const ts = new Date().toISOString();
  const extra = meta ? " " + JSON.stringify(meta) : "";
  console.log(`[SUPERVISOR] ${ts} ${level} ${msg}${extra}`);
}

disconnect() {
  if (!isConnected) return;  // 幂等
  isConnected = false;       // 先改状态，再做清理
  if (wsClient) {
    try {
      wsClient.close({ force: true });
    } catch (err) {
      log("WARN", "fallback_ws_close_error", { error: String(err) });
    }
    wsClient = null;
  }
}

let text = "";
try {
  const content = JSON.parse(String(message.content ?? "{}"));
  text = String(content.text ?? "").trim();
} catch {
  return; // JSON 解析失败直接跳过这条消息，不报错
}

// src/cli.ts
export async function run(argv?: string[]): Promise<void> {
  const program = createProgram()
 
  try {
    await program.parseAsync(argv ?? process.argv)
  } catch (error) {
    handleError(error)
  }
}

// 命令实现中
import { UserError, NetworkError } from '../core/error.js'
 
// 用户错误 → 给提示
throw new UserError('未找到 package.json', '请在项目根目录下运行此命令')
 
// 网络错误 → 带上下文
throw new NetworkError('API 限流', 429, 'https://api.github.com/repos')
 
// 其他错误 → 直接 throw，handleError 会兜底
throw new Error('不应该走到这里')

export function registerDoctorCommand(program: Command): void {
  program
    .command('doctor')
    .description('检查项目和 repox 环境的健康状态')
    .action(async () => {
      logger.title('repox 健康检查')
 
      const checks: CheckResult[] = []
 
      // 1. Node.js 版本
      const nodeVersion = process.version
      const major = parseInt(nodeVersion.slice(1).split('.')[0], 10)
      checks.push({
        name: 'Node.js 版本',
        status: major >= 18 ? 'pass' : 'fail',
        message: major >= 18 ? nodeVersion : `${nodeVersion}（需要 >= 18.0.0）`,
      })
 
      // 2. Git 是否可用
      checks.push(checkCommand('Git', 'git --version'))
 
      // 3. 是否在 Git 仓库中
      checks.push({
        name: 'Git 仓库',
        status: isGitRepo() ? 'pass' : 'warn',
        message: isGitRepo() ? '当前目录是 Git 仓库' : '当前目录不是 Git 仓库',
      })
 
      // ... 更多检查项
 
      // 打印汇总
      if (failCount > 0) {
        logger.error(`${failCount} 项检查未通过，请修复后再试`)
      } else if (warnCount > 0) {
        logger.warn(`所有必要检查通过，${warnCount} 项警告`)
      } else {
        logger.success('所有检查通过，环境正常')
      }
    })
}

interface CheckResult {
  name: string
  status: 'pass' | 'warn' | 'fail'
  message: string
}

function checkCommand(name: string, command: string): CheckResult {
  try {
    const output = execSync(command, {
      encoding: 'utf-8',
      stdio: ['pipe', 'pipe', 'pipe'],
    }).trim()
    return { name, status: 'pass', message: output }
  } catch {
    return { name, status: 'fail', message: '未安装或不可用' }
  }
}

repox 健康检查
────────────────────
  ✔ Node.js 版本: v20.11.0
  ✔ Git: git version 2.43.0
  ✔ Git 仓库: 当前目录是 Git 仓库
  ✔ package.json: 已找到
  ✔ TypeScript: tsconfig.json 已找到
  ⚠ GitHub 认证: 未配置（部分功能不可用）
  ⚠ AI API Key: 未配置（AI 功能不可用）
  ✔ npm: 10.2.4

所有必要检查通过，2 项警告