用途
dev-error-explainers 用于在离线、确定性的前提下解释开发者常见错误。用户粘贴一段错误文本，工具识别错误类型，给出原因和修复建议，并尽可能引用官方文档来源。它不依赖 LLM、API、网络或遥测，相同输入始终返回相同结果。
主要能力
项目包含七个小型、纯 JavaScript、零依赖的模块，分别处理：
- CORS 错误
- ESM/CommonJS 模块错误
- npm ERESOLVE 依赖解析错误
- ChunkLoadError
- Postgres/Supabase DATABASE_URL 错误
- Postgres 连接错误
- Next.js 构建错误
每个模块识别开发者粘贴的精确错误文本（来自浏览器控制台、npm、next build、curl -I、Node.js 堆栈跟踪等），解释发生原因，并返回具体修复方案，尽可能附上主要来源链接（MDN、Node.js 文档、npm 文档、PostgreSQL 文档、Supabase 文档等）。
同一引擎可作为库、CLI、GitHub Action 和 MCP 服务器运行。其中六个模块为 iloveblogs.blog/tools 上的免费工具提供支持，可在浏览器中试用。
使用方式
作为库
需要 Node.js 20 或更高版本，仅支持 ES 模块。所有内容可从包根导入，每个模块也可单独导入。
diagnose(text) 将所有模块的结果映射为统一结构，带有稳定的规则 ID，并在分析前对输入进行脱敏。未知输入返回 { matched: false, results: [] }，不会给出最接近的猜测。
redact(text) 也可从 dev-error-explainers/redact 导出。
作为 CLI
可将失败命令的输出通过管道传入，或传入日志文件。数据不会发送到任何地方。
标志包括：--only cors|esm|eresolve|build|database-url|database-connection|chunk-cache、--json、--node <version>、--client prisma|drizzle|pg|psql、--html-headers <file> --chunk-headers <file>、--help、--version。
npx dev-error-explainers mcp 可启动 MCP 服务器。
退出码：0 表示识别到错误，2 表示未识别（不做猜测），64 表示用法错误。连接字符串始终以密码掩码形式打印。
在 CI 中使用（GitHub Action）
当某个步骤失败时，Action 读取保存的日志，将原因和修复写入作业摘要，并在日志中指明检出文件时对文件和行进行注释。无网络、无 LLM、无令牌。
从 AI 助手使用（MCP）
提供一个 MCP 服务器，包含一个工具 explain_error，让助手在猜测之前先对照文档化原因检查粘贴的错误。离线且确定性；未识别输入会如实报告。支持 Claude Code、Claude Desktop、Cursor、VS Code。
在 Claude Code 中使用（插件：skill + MCP）
该仓库同时是一个 Claude Code 插件市场。插件捆绑 MCP 服务器和一个 skill，告诉 Claude 何时调用它。
适用场景
- 开发者在本地或 CI 中遇到常见错误，希望快速获得确定性解释和修复建议。
- 在无网络或不允许调用外部 API 的环境中排查错误。
- 在 GitHub Actions 中自动分析失败日志并生成摘要。
- 让 AI 助手在回答错误相关问题前先查询文档化原因，减少猜测。
限制
- 需要 Node.js 20 或更高版本，仅支持 ES 模块。
- 未识别的错误会报告为未识别，不会猜测。
- 脱敏有局限：CLI、Action 和 MCP 服务器在分析前通过
redact()处理输入，但 DATABASE_URL doctor 例外，它读取原始postgres://行（密码的确切字符决定诊断），但从不打印该密码。作为库直接使用时，七个模块中有六个会在回显前掩码疑似机密；构建错误解码器不会，它会原样引用构建输出的匹配行。 - 构建错误解码器没有主要来源 URL，其链接指向作者网站 iloveblogs.blog 上的文章。
- 并非每条规则都引用来源。
维护与反馈
由 Mahdi Ben Rhouma 维护。CI 在 Node.js 20、22 和 24 上运行测试套件。未识别的错误可通过 issue 提交精确文本、产生它的命令和工具版本；新规则需要基于真实错误构建测试。错误的诊断也被视为 bug，有单独的模板。
