如何为 ESLint 编写高质量 Bug 报告templates/bug-report.md模板逐段解析与底层原理【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslintBug 报告是开源项目最宝贵的原材料而一份信息不完整的报告往往会让维护者在三番五次追问中耗尽时间。本文以 ESLint 仓库中的 Bug 报告模板 为主线逐段拆解其中每个字段的含义、填写方法与背后的实现原理——包括npx eslint --env-info的源码级工作机制、常用 parser 的适用场景、配置的最小复现写法以及期望行为与实际行为如何帮助维护者快速定位问题。读完本文你既能写出让 ESLint 维护者一次就能复现的高质量 Issue也能更深入地理解 ESLint 的 CLI 与运行时信息收集机制。为什么 ESLint 需要一份标准化的 Bug 报告模板ESLint 是一个跨平台、可高度配置的 JavaScript 静态分析工具其问题往往与运行环境强相关同一份配置在 Node.js 18 与 Node.js 22 下可能行为不同本地全局安装的 ESLint 与项目内局部安装的版本冲突也可能引发诡异现象。如果报告者只丢下一句规则不生效维护者根本无法判断问题出在环境、配置还是代码本身。模板的第一行就给出了答案——维护者需要尽可能多的细节来高效处理 Issue。正如官方贡献文档 report-bugs.md 所述如果团队不得不在 triage分诊阶段反复向报告者索要细节那么本应用于修复问题的时间就被白白消耗掉了。模板的设计目标就是让报告者在第一次提交时就把所有诊断要素给齐让维护者拿到手即可复现、定位、修复。从仓库源码结构看这套模板还配套了完整的贡献流程模板文件位于 templates/bug-report.md与 规则变更提案模板、新规则提案模板、博客文章模板 等并列是 ESLint 社区贡献体系的一部分。第一部分环境信息与npx eslint --env-info模板开头要求报告者填写 7 项环境信息Node versionNode.js 版本npm versionnpm 版本Local ESLint version项目本地安装的 ESLint 版本Global ESLint version全局安装的 ESLint 版本Operating System操作系统以及命令提示中的当前 ESLint 实际执行版本这些字段并非让报告者手工去node -v、npm -v逐一查询而是可以通过一条命令一次性获取——模板中标注的正是npx eslint --env-info--env-info的底层实现在 lib/options.js 中--env-info被定义为一个布尔型 CLI 选项默认值为false功能描述为 Output execution environment information。注意它没有参数直接以标志形式使用。在 lib/cli.js 中该选项的处理逻辑清晰可见if (options.envInfo) { try { log.info(RuntimeInfo.environment()); return 0; } catch (err) { debug(Error retrieving environment info); log.error(err.message); return 2; } }即一旦检测到--env-infoCLI 会调用RuntimeInfo.environment()并直接退出返回码 0完全不会执行任何 lint 检查。这与官方 CLI 文档 command-line-interface.md 的说明一致When you use this flag, the CLI does not perform linting.真正的信息收集逻辑在 lib/shared/runtime-info.js 中实现输出内容对应模板的 5 个核心字段模板字段源码实现获取方式Node versionprocess.version直接读取进程内置属性npm versiongetBinVersion(npm)执行npm --versionLocal ESLint versiongetNpmPackageVersion(eslint, { global: false })执行npm ls --depth0 --json eslintGlobal ESLint versiongetNpmPackageVersion(eslint, { global: true })执行npm ls --depth0 --json eslint -gOperating Systemos.platform() os.release()读取 Node 内置os模块几个值得注意的实现细节结果缓存execCommand使用Map按cmd args做键缓存结果避免重复执行外部命令runtime-info.js。版本号归一化normalizeVersionStr会为不带v前缀的版本号补上v保证所有字段格式统一runtime-info.js。Currently used 标记getNpmPackageVersion通过比较npm bin -g输出的全局 bin 路径与当前执行进程路径的父子关系判断当前实际使用的是本地还是全局的 ESLint并在版本号后追加(Currently used)标注runtime-info.js。这一点非常重要——它直接回应了模板中同时询问本地版本与全局版本的原因两个版本都可能被实际加载而npm ls的检测结果会明确告诉你到底是谁在生效。Not found 分支当npm ls返回空 JSON 对象全局未安装或依赖树中不存在 eslint 时会返回 Not found避免误报runtime-info.js。输出格式统一为Environment Info:开头的多行文本。仓库中对应的单元测试 tests/lib/shared/runtime-info.js 通过 stub 掉spawn.sync、process.version、os.platform等精确断言了每行输出的内容与顺序例如模拟本地项目输出v6.3.0 (Currently used)、全局路径输出v6.11.3等场景。典型的运行结果大致如下字段顺序即模板顺序Environment Info: Node version: v20.11.0 npm version: v10.2.4 Local ESLint version: v9.0.0 (Currently used) Global ESLint version: v8.57.0 Operating System: linux 5.15.0-91-generic填写建议直接复制npx eslint --env-info的完整输出到模板对应字段不要手工精简。注意使用npx而非eslint可以确保执行的是项目本地依赖中的 ESLint这与模板的初衷一致。第二部分你使用的是哪个 Parser模板第二段要求报告者从下列选项中以 X 勾选唯一的 parserDefault (Espree)——默认解析器typescript-eslint/parserbabel/eslint-parservue-eslint-parserangular-eslint/template-parserOther其他需在后续说明中注明具体名称为什么 parser 如此关键parser 决定了 ESLint 如何把源代码解析成可供规则遍历的 AST。同一段代码在不同 parser 下生成的 AST 结构不同规则的行为自然可能不同——比如typescript-eslint/parser会生成包含TSInterfaceDeclaration等 TypeScript 节点的 AST而默认的 Espree 根本解析不了 TypeScript 语法。模板把 parser 单独列为一问正是为了让维护者第一时间排除或确认解析层的嫌疑。从 lib/languages/js/index.js 的源码可以看出 ESLint 的默认 parser 机制语言选项的默认值中parser: espreeindex.js即未显式配置时使用 Espree源码还通过isEspree()判断当前 parser 是否为 Espree以便在必要时修正parserOptions的sourceType、ecmaFeatures.globalReturn等参数保证与 Espree 的解析约定一致index.js实际解析时ESLint 优先调用 parser 的parseForESLint若存在否则回退到parse以兼容两类自定义 parserindex.js。常见 parser 的适用场景EspreeESLint 官方维护、默认使用的 JavaScript parser只支持标准 ECMAScript 语法如果问题代码不含 JSX/TS 等扩展语法通常就是它。typescript-eslint/parser解析 TypeScript 代码的标准方案几乎总是与typescript-eslint插件配套使用。babel/eslint-parser需要 Babel 做语法转换如实验性提案语法、Flow 等时的选择需同时配置babel/core。vue-eslint-parser解析.vue单文件组件内部实际委托 Espree 等解析 template 之外的脚本部分。angular-eslint/template-parser专门解析 Angular 模板语法。Other任意自定义 parser填写时务必给出完整的包名与版本号。填写建议如果没配置过 parser勾选Default (Espree)即可不要凭感觉猜测可以从下面的配置片段中直接确认。第三部分提供完整配置模板第三段要求报告者在details折叠块中粘贴完整配置// 将你的配置粘贴到此处ESLint 当前使用 flat config 体系配置文件位于项目根目录的 eslint.config.js。本仓库自身的 ESLint 配置就是一份很好的真实样例——它从eslint/js引入 recommended 规则集再按模块类型浏览器代码、Node 代码、测试代码、配置文件等分别下发不同的规则覆盖。一个可供参考的完整配置示例包含规则、语言选项与 ignoresimport js from eslint/js; export default [ js.configs.recommended, { files: [src/**/*.js], languageOptions: { ecmaVersion: 2022, sourceType: module, }, rules: { no-unused-vars: error, quotes: [error, single], }, }, { ignores: [dist/**, node_modules/**], }, ];填写建议粘贴完整配置不要只贴出疑似出问题的那一两条规则——规则之间的交互、languageOptions、plugins、settings都可能是根因若配置分散在多个文件如eslint.config.js引用了其他模块请一并提供或说明若使用旧版eslintrc体系.eslintrc.js/.eslintrc.json请在报告中注明因为该体系已逐渐被 flat config 取代可以在提交前自行运行npx eslint --print-config 某文件查看合并后的最终生效配置这一步能帮你排除配置没生效这类常见误解也让报告更加精准。第四部分你做了什么附最小复现代码模板第四段要求What did you do? Please include the actual source code causing the issue.这是整个报告中最核心的部分要求包含实际触发问题的源码必须是可复现的代码片段不要贴整个项目。执行的命令例如npx eslint src/foo.js、npx eslint . --fix等尽量精确到参数。一个优质的最小复现应满足最小化删去与问题无关的代码保留能稳定触发的最小片段自包含包含必要的语法上下文如export表明它是模块让维护者无需猜测可运行给出从空目录到触发问题的完整命令序列例如npm init -y npm install eslint npx eslint --init # 或手写 eslint.config.js # 将下方代码保存为 test.js 后执行 npx eslint test.js对应代码// test.js const greeting hello console.log(greeting)填写建议如果问题只在特定场景出现如与某个插件规则冲突请把插件版本、相关规则的配置一并给出如果问题文件较多优先提供单个最小文件。第五部分你期望发生什么模板第五段What did you expect to happen?这一问看似简单实则非常重要它帮助维护者确认这是行为不符合文档/规范的 bug还是报告者对工具行为的误解——后者应转入 Discussion 而非 Issue它界定了修复的验收标准期望行为写得越具体维护者越容易判断修复方案是否正确结合文档给出依据如官方文档 command-line-interface.md 对某个选项的说明可以让期望更具说服力。示例期望no-unused-vars规则在配置为error时对该文件输出 1 条错误而不是 0 条或期望--env-info在执行后立即退出且不进行 lint。第六部分实际发生了什么附原始输出模板第六段What actually happened? Please include the actual, raw output from ESLint.这一问的关键词是actual, raw output——即完整复制 ESLint 的终端输出包括错误信息、行号、规则名、严重级别保留原始格式不要手动美化或删行若存在异常堆栈stack trace必须原样粘贴说明退出码exit code——例如 lib/cli.js 中环境信息获取失败时返回码 2而 lint 错误通常返回码 1退出码本身也是诊断线索若涉及自动修复--fix说明修复前后的代码差异。原始输出示例/path/to/test.js 2:10 error greeting is assigned a value but never used no-unused-vars ✖ 1 problem (1 error, 0 warnings)填写建议优先把输出放进代码块以保留空白与缩进如果输出较长截取关键片段但说明省略范围同时补上输出与期望行为之间的差异对照这会极大降低维护者的阅读成本。从模板到 Issue几项提升效率的实践原则环境信息用命令生成不要手填npx eslint --env-info的输出精确、格式统一且能自动标记实际生效的本地/全局版本这是模板首行放置该命令的原因。先自查再上报提交前可自行运行--print-config核对最终配置、尝试升级/降级 Node 或 ESLint 版本、在干净目录中复现一次很多bug其实源于环境或配置问题。区分 Bug 与提问如 report-bugs.md 所述如果只是询问用法而非报告缺陷应走 Discussions 而非 Bug Issue以免干扰维护者的修复节奏。配置、代码、输出三者对应一份完整报告应能让人仅凭报告本身就能按步骤复现这是模板四、五、六段协同设计的目标。附上必要的仓库路径如果问题与 ESLint 自身源码相关引用相关文件能加速定位例如规则实现位于 lib/rules/、CLI 入口位于 lib/cli.js、运行时信息工具位于 lib/shared/runtime-info.js。小结ESLint 的 bug-report.md 模板 虽然只有三十余行却精准覆盖了复现一个 lint 缺陷所需的全部要素环境由--env-info一站式提供底层实现于 runtime-info.js、parser、完整配置、最小复现代码、期望行为与实际输出。维护者拿到这样一份报告就能跳过漫长的追问循环直接进入定位与修复阶段。对报告者而言遵循这份模板写 Issue 的过程本身也是一次对 ESLint 运行机制——从 CLI 选项解析lib/options.js、执行流程lib/cli.js到 parser 与配置体系lib/languages/js/index.js——的深度梳理堪称一次填写双重收获。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考