ESLint init-declarations 规则完全指南统一变量声明时的初始化风格支持 JavaScript 与 TypeScript【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint本篇技术指南聚焦 ESLint 内置规则init-declarations讲解如何通过两条配置选项统一变量是否应在声明语句中立即初始化的代码风格。无论你的团队希望强制let/var声明即赋值还是要求先声明后赋值都可以借助该规则在 CI 与编辑器中被自动检查。读完本文你将掌握always、never与ignoreForLoopInit三种配置的完整语义、for 循环等边界场景的处理逻辑、TypeScript 声明语法的兼容行为以及该规则与no-unassigned-vars规则的分工与组合用法。规则背景JavaScript 的两种变量初始化方式在 JavaScript 中变量可以在声明的同时赋值也可以先声明、稍后再通过赋值语句初始化。以下代码中foo在声明时即被初始化而bar则在if/else分支中才被赋值let foo 1; let bar; if (foo) { bar 1; } else { bar 2; }两种写法本身没有对错但如果团队内混用两种风格代码可读性与一致性就会下降。ESLint 内置规则init-declarations类型为suggestion即建议类规则正是为统一这一风格而设计。其官方定位可见 规则文档 与 源码实现规则类型suggestion适用方言JavaScript 与 TypeScript源码中dialects: [JavaScript, TypeScript]是否推荐启用recommended: false即不会出现在eslint:recommended中需要团队显式开启是否冻结frozen: true表示该规则的行为已被冻结、不会在后续版本中发生破坏性变更例如下面的代码中foo声明即初始化bar声明后赋值init-declarations会依据配置决定哪一种是允许的let foo 1; let bar; bar 2;配置选项字符串 可选对象该规则接受两个配置项字符串模式必须是always默认值或never。规则适用于var、let、const、using、await using五类声明但当模式为never时const、using、await using会被自动忽略——因为不给这些变量初始化会产生语法解析错误如const a;直接抛错。对象参数目前仅支持ignoreForLoopInit布尔值。当模式为never时如果开启该选项则允许在for循环中声明并初始化变量因为这是非常典型的惯用法。三种典型配置变量必须在声明时初始化默认行为{ init-declarations: [error, always] }变量禁止在声明时初始化{ init-declarations: [error, never] }变量禁止在声明时初始化但 for 循环除外{ init-declarations: [error, never, { ignoreForLoopInit: true }] }在 flat configESLint 9 默认配置格式中同样的规则被写在rules字段下用法完全一致。在源码中该规则的默认选项由defaultOptions: [always]定义见 lib/rules/init-declarations.js因此init-declarations: error等价于[error, always]。配置模式schema细节从 源码的 schema 定义 可以看到该规则的严格参数校验规则always模式接受一个数组最多 1 项且只能是字符串always即不允许携带额外对象参数never模式接受一个数组最多 2 项第二项必须是对象且仅允许ignoreForLoopInit: boolean一个属性additionalProperties: false意味着传入其他任何属性都会触发配置校验错误。这意味着[error, always, { ignoreForLoopInit: true }]这类组合是非法的ignoreForLoopInit只与never配套使用。模式一always —— 强制声明即初始化always是默认模式要求所有变量在声明语句中必须带初始值。错误的代码示例/*eslint init-declarations: [error, always]*/ function foo() { var bar; let baz; }以上代码中bar、baz均未在声明时初始化会分别触发错误信息Variable bar should be initialized on declaration.对应源码中的messages.initialized见 lib/rules/init-declarations.js。正确的代码示例/*eslint init-declarations: [error, always]*/ function foo() { var bar 1; let baz 2; const qux 3; using quux getSomething(); } async function foobar() { await using quux getSomething(); }注意正确示例中using与await using显式资源管理语法需要较新的 ECMAScript 版本支持同样必须初始化。一个容易被忽略的边界always模式下for循环的声明位置会被视为已初始化。例如for (var i 0; i 1; i) {}是合法的因为声明出现在ForStatement的init位置。这一行为源于源码中的isInitialized辅助函数见 lib/rules/init-declarations.js当声明位于ForStatement.init或ForInStatement/ForOfStatement的left位置时会被判定为已初始化。但循环体内单独的裸声明仍会被检查例如for (var a in []) var foo;中的var foo依然违规。模式二never —— 禁止声明即初始化never模式与always相反要求变量先声明、后赋值。错误的代码示例/*eslint init-declarations: [error, never]*/ function foo() { var bar 1; let baz 2; for (let i 0; i 1; i) {} }bar、baz在声明时初始化违规for (let i 0; ...)中i也在声明时初始化同样违规除非开启ignoreForLoopInit。它们会触发错误信息Variable bar should not be initialized on declaration.对应源码中的messages.notInitialized。正确的代码示例/*eslint init-declarations: [error, never]*/ function foo() { var bar; let baz; const buzz 1; using quux getSomething(); } async function foobar() { await using quux getSomething(); }注意const buzz 1与using quux getSomething()虽然声明即初始化却不算违规。这正是前面提到的never模式会忽略const、using、await using三类变量。在 源码实现 中这三类绑定被统一存放在CONSTANT_BINDINGS集合中检查逻辑为mode never !CONSTANT_BINDINGS.has(kind) // const/using/await using 直接跳过 initialized !isIgnoredForLoopfor 循环的判定细节never模式下for (var i 0; i 1; i) {}、for (var foo in []) {}、for (var foo of []) {}中的循环变量声明均会被判定为已初始化而报错。测试用例完整覆盖了这三种场景见 tests/lib/rules/init-declarations.js分别对应ForStatement、ForInStatement、ForOfStatement三种节点类型。循环头之外的同名变量声明则不受影响。选项 ignoreForLoopInit —— 放行 for 循环由于在 for 循环头部初始化计数器是极其常见的写法never模式为此专门提供了ignoreForLoopInit逃生口。开启后for 循环声明位置的初始化将不再报错/*eslint init-declarations: [error, never, { ignoreForLoopInit: true }]*/ for (let i 0; i 1; i) {}对应的源码逻辑在create函数的VariableDeclaration:exit监听器中见 lib/rules/init-declarations.jsisIgnoredForLoop params.ignoreForLoopInit isForLoop(node.parent);其中isForLoop识别三种节点类型ForStatement、ForInStatement、ForOfStatement见 lib/rules/init-declarations.js因此该选项对三种 for 循环形态均生效。测试中对for(var i 0; ...)、for (var foo in [])、for (var foo of [])三种写法在开启该选项后都被判为合法。重要提示ignoreForLoopInit只在never模式下有意义。如果你选择的是always模式for 循环头部的声明本来就被视为已初始化无需额外配置。TypeScript 支持与 declare 声明豁免该规则原生支持 TypeScript 类型语法类型注解不会影响判定结果。同时源码中专门处理了declare声明位于declare修饰的变量声明或declare namespace内部的变量不会被检查。错误的 TypeScript 代码never 模式/* eslint init-declarations: [error, never] */ let arr: string[] [arr, ar]; const class1 class NAME { constructor() { var name1: string hello; } }; namespace myLib { let numberOfGreetings: number 2; }arr、name1、numberOfGreetings均在声明时初始化且它们所在位置不属于declare声明因此全部报错。错误的 TypeScript 代码always 模式/* eslint init-declarations: [error, always] */ namespace myLib { let numberOfGreetings: number; } namespace myLib1 { const foo: number; namespace myLib2 { let bar: string; namespace myLib3 { let baz: object; } } }注意这里的namespace没有declare前缀内的未初始化变量在always模式下同样会被报告——只有declare namespace才能豁免。最后一个错误用例还验证了嵌套 namespace也会被递归检查。正确的 TypeScript 代码两种模式均通过/* eslint init-declarations: [error, never] */ declare const foo: number; declare namespace myLib { let numberOfGreetings: number; } interface GreetingSettings { greeting: string; duration?: number; color?: string; }declare const foo: number;没有初始化却合法是因为它带declare修饰符declare namespace内部的变量同理。interface本身只是类型声明不产生运行时变量自然不受影响。上述两组正确示例同时适用于always与never两种模式你可以直接复制到自己的配置中验证。从 源码实现 可以看到规则通过监听TSModuleDeclaration节点的进入与退出维护insideDeclaredNamespace状态标志TSModuleDeclaration(node) { if (node.declare) { insideDeclaredNamespace true; } }, TSModuleDeclaration:exit(node) { if (node.declare) { insideDeclaredNamespace false; } },然后在VariableDeclaration:exit中只要遇到node.declare或处于insideDeclaredNamespace状态就提前返回、跳过检查。这一点与no-unassigned-vars规则的TSModuleDeclaration[declaretrue]处理方式如出一辙见 lib/rules/no-unassigned-vars.js。另外只有当声明标识符是Identifier即id.type Identifier时才会上报解构模式等节点会被跳过。源码级解析规则的执行机制规则的全部判定逻辑集中在 lib/rules/init-declarations.js 的create函数中核心是VariableDeclaration:exit遍历器。每个声明节点会依次经过三个判断是否豁免node.declare或位于declare namespace内部 → 跳过是否已初始化调用isInitialized非 for 循环场景看node.init是否存在for 循环场景看声明是否位于循环头部的init/left位置是否命中模式always且未初始化 → 报initializednever且非const/using/await using、已初始化、且未命中ignoreForLoopInit→ 报notInitialized。上报时使用context.report携带messageId与变量名idName最终展示为如Variable foo should be initialized on declaration.的人类可读信息。规则的完整行为由 tests/lib/rules/init-declarations.js 中的RuleTester用例守护JavaScript 用例覆盖了多声明混写如var foo, bar false, baz;只报告foo与baz、函数作用域、for 循环三类变体TypeScript 用例通过typescript-eslint/parser驱动则覆盖了declare、namespace、嵌套 namespace、interface、类内部变量、类型别名等场景。值得一提的是规则的元信息中docs.recommended: false意味着它属于团队可选风格规则但frozen: true保证了即使未来 ESLint 大版本迭代其行为也不会悄然改变。规则通过 lib/rules/index.js 注册到内置规则集合同时被 eslint-all 配置 收录init-declarations: error也就是说开启全部规则时它会被激活。关联规则与 no-unassigned-vars 的分工本规则在文档中声明了关联规则no-unassigned-vars见 规则元数据 的related_rules字段。两者视角互补init-declarations关注风格变量应在哪里初始化声明时 vs 声明后与变量是否真的被使用无关no-unassigned-vars关注正确性let/var变量被读取却从未被赋值导致其永远为undefined几乎一定是编程错误见 no-unassigned-vars 文档 与 源码。例如let status; if (status ready) {...}中status从未被赋值no-unassigned-vars会判定这是 bug而let status; status check(); console.log(status);这类先声明后赋值的写法no-unassigned-vars不会报错但init-declarations: [error, always]会要求你把声明合并为let status check();。no-unassigned-vars属于recommended: true的问题类规则且对declare声明、const、using、await using等同样有豁免处理两者搭配使用可以同时覆盖一致性与潜在 bug两个维度。何时不该使用本规则官方文档给出的建议是当你不在意变量的初始化方式时可以关闭此规则。具体而言以下团队场景可以放心停用代码库中两种风格并存且没有统一意图强行约束反而引发大量与逻辑无关的改动噪音项目大量使用声明后条件赋值模式如错误处理变量、惰性初始化always模式会频繁误伤never模式又可能不适配已有no-unassigned-vars承担正确性检查团队更倾向于让声明风格保持自由。总结init-declarations是一把简单但精准的风格规尺always默认强制声明即初始化never强制先声明后赋值ignoreForLoopInit为 for 循环提供豁免它对var、let、const、using、await using五种声明类型差异对待并对 TypeScript 的declare、declare namespace声明网开一面。配合 规则文档、源码实现 与 完整测试 查阅你可以在团队中快速评估并落地这一风格约束。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
ESLint init-declarations 规则完全指南统一变量声明时的初始化风格支持 JavaScript 与 TypeScript【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint本篇技术指南聚焦 ESLint 内置规则init-declarations讲解如何通过两条配置选项统一变量是否应在声明语句中立即初始化的代码风格。无论你的团队希望强制let/var声明即赋值还是要求先声明后赋值都可以借助该规则在 CI 与编辑器中被自动检查。读完本文你将掌握always、never与ignoreForLoopInit三种配置的完整语义、for 循环等边界场景的处理逻辑、TypeScript 声明语法的兼容行为以及该规则与no-unassigned-vars规则的分工与组合用法。规则背景JavaScript 的两种变量初始化方式在 JavaScript 中变量可以在声明的同时赋值也可以先声明、稍后再通过赋值语句初始化。以下代码中foo在声明时即被初始化而bar则在if/else分支中才被赋值let foo 1; let bar; if (foo) { bar 1; } else { bar 2; }两种写法本身没有对错但如果团队内混用两种风格代码可读性与一致性就会下降。ESLint 内置规则init-declarations类型为suggestion即建议类规则正是为统一这一风格而设计。其官方定位可见 规则文档 与 源码实现规则类型suggestion适用方言JavaScript 与 TypeScript源码中dialects: [JavaScript, TypeScript]是否推荐启用recommended: false即不会出现在eslint:recommended中需要团队显式开启是否冻结frozen: true表示该规则的行为已被冻结、不会在后续版本中发生破坏性变更例如下面的代码中foo声明即初始化bar声明后赋值init-declarations会依据配置决定哪一种是允许的let foo 1; let bar; bar 2;配置选项字符串 可选对象该规则接受两个配置项字符串模式必须是always默认值或never。规则适用于var、let、const、using、await using五类声明但当模式为never时const、using、await using会被自动忽略——因为不给这些变量初始化会产生语法解析错误如const a;直接抛错。对象参数目前仅支持ignoreForLoopInit布尔值。当模式为never时如果开启该选项则允许在for循环中声明并初始化变量因为这是非常典型的惯用法。三种典型配置变量必须在声明时初始化默认行为{ init-declarations: [error, always] }变量禁止在声明时初始化{ init-declarations: [error, never] }变量禁止在声明时初始化但 for 循环除外{ init-declarations: [error, never, { ignoreForLoopInit: true }] }在 flat configESLint 9 默认配置格式中同样的规则被写在rules字段下用法完全一致。在源码中该规则的默认选项由defaultOptions: [always]定义见 lib/rules/init-declarations.js因此init-declarations: error等价于[error, always]。配置模式schema细节从 源码的 schema 定义 可以看到该规则的严格参数校验规则always模式接受一个数组最多 1 项且只能是字符串always即不允许携带额外对象参数never模式接受一个数组最多 2 项第二项必须是对象且仅允许ignoreForLoopInit: boolean一个属性additionalProperties: false意味着传入其他任何属性都会触发配置校验错误。这意味着[error, always, { ignoreForLoopInit: true }]这类组合是非法的ignoreForLoopInit只与never配套使用。模式一always —— 强制声明即初始化always是默认模式要求所有变量在声明语句中必须带初始值。错误的代码示例/*eslint init-declarations: [error, always]*/ function foo() { var bar; let baz; }以上代码中bar、baz均未在声明时初始化会分别触发错误信息Variable bar should be initialized on declaration.对应源码中的messages.initialized见 lib/rules/init-declarations.js。正确的代码示例/*eslint init-declarations: [error, always]*/ function foo() { var bar 1; let baz 2; const qux 3; using quux getSomething(); } async function foobar() { await using quux getSomething(); }注意正确示例中using与await using显式资源管理语法需要较新的 ECMAScript 版本支持同样必须初始化。一个容易被忽略的边界always模式下for循环的声明位置会被视为已初始化。例如for (var i 0; i 1; i) {}是合法的因为声明出现在ForStatement的init位置。这一行为源于源码中的isInitialized辅助函数见 lib/rules/init-declarations.js当声明位于ForStatement.init或ForInStatement/ForOfStatement的left位置时会被判定为已初始化。但循环体内单独的裸声明仍会被检查例如for (var a in []) var foo;中的var foo依然违规。模式二never —— 禁止声明即初始化never模式与always相反要求变量先声明、后赋值。错误的代码示例/*eslint init-declarations: [error, never]*/ function foo() { var bar 1; let baz 2; for (let i 0; i 1; i) {} }bar、baz在声明时初始化违规for (let i 0; ...)中i也在声明时初始化同样违规除非开启ignoreForLoopInit。它们会触发错误信息Variable bar should not be initialized on declaration.对应源码中的messages.notInitialized。正确的代码示例/*eslint init-declarations: [error, never]*/ function foo() { var bar; let baz; const buzz 1; using quux getSomething(); } async function foobar() { await using quux getSomething(); }注意const buzz 1与using quux getSomething()虽然声明即初始化却不算违规。这正是前面提到的never模式会忽略const、using、await using三类变量。在 源码实现 中这三类绑定被统一存放在CONSTANT_BINDINGS集合中检查逻辑为mode never !CONSTANT_BINDINGS.has(kind) // const/using/await using 直接跳过 initialized !isIgnoredForLoopfor 循环的判定细节never模式下for (var i 0; i 1; i) {}、for (var foo in []) {}、for (var foo of []) {}中的循环变量声明均会被判定为已初始化而报错。测试用例完整覆盖了这三种场景见 tests/lib/rules/init-declarations.js分别对应ForStatement、ForInStatement、ForOfStatement三种节点类型。循环头之外的同名变量声明则不受影响。选项 ignoreForLoopInit —— 放行 for 循环由于在 for 循环头部初始化计数器是极其常见的写法never模式为此专门提供了ignoreForLoopInit逃生口。开启后for 循环声明位置的初始化将不再报错/*eslint init-declarations: [error, never, { ignoreForLoopInit: true }]*/ for (let i 0; i 1; i) {}对应的源码逻辑在create函数的VariableDeclaration:exit监听器中见 lib/rules/init-declarations.jsisIgnoredForLoop params.ignoreForLoopInit isForLoop(node.parent);其中isForLoop识别三种节点类型ForStatement、ForInStatement、ForOfStatement见 lib/rules/init-declarations.js因此该选项对三种 for 循环形态均生效。测试中对for(var i 0; ...)、for (var foo in [])、for (var foo of [])三种写法在开启该选项后都被判为合法。重要提示ignoreForLoopInit只在never模式下有意义。如果你选择的是always模式for 循环头部的声明本来就被视为已初始化无需额外配置。TypeScript 支持与 declare 声明豁免该规则原生支持 TypeScript 类型语法类型注解不会影响判定结果。同时源码中专门处理了declare声明位于declare修饰的变量声明或declare namespace内部的变量不会被检查。错误的 TypeScript 代码never 模式/* eslint init-declarations: [error, never] */ let arr: string[] [arr, ar]; const class1 class NAME { constructor() { var name1: string hello; } }; namespace myLib { let numberOfGreetings: number 2; }arr、name1、numberOfGreetings均在声明时初始化且它们所在位置不属于declare声明因此全部报错。错误的 TypeScript 代码always 模式/* eslint init-declarations: [error, always] */ namespace myLib { let numberOfGreetings: number; } namespace myLib1 { const foo: number; namespace myLib2 { let bar: string; namespace myLib3 { let baz: object; } } }注意这里的namespace没有declare前缀内的未初始化变量在always模式下同样会被报告——只有declare namespace才能豁免。最后一个错误用例还验证了嵌套 namespace也会被递归检查。正确的 TypeScript 代码两种模式均通过/* eslint init-declarations: [error, never] */ declare const foo: number; declare namespace myLib { let numberOfGreetings: number; } interface GreetingSettings { greeting: string; duration?: number; color?: string; }declare const foo: number;没有初始化却合法是因为它带declare修饰符declare namespace内部的变量同理。interface本身只是类型声明不产生运行时变量自然不受影响。上述两组正确示例同时适用于always与never两种模式你可以直接复制到自己的配置中验证。从 源码实现 可以看到规则通过监听TSModuleDeclaration节点的进入与退出维护insideDeclaredNamespace状态标志TSModuleDeclaration(node) { if (node.declare) { insideDeclaredNamespace true; } }, TSModuleDeclaration:exit(node) { if (node.declare) { insideDeclaredNamespace false; } },然后在VariableDeclaration:exit中只要遇到node.declare或处于insideDeclaredNamespace状态就提前返回、跳过检查。这一点与no-unassigned-vars规则的TSModuleDeclaration[declaretrue]处理方式如出一辙见 lib/rules/no-unassigned-vars.js。另外只有当声明标识符是Identifier即id.type Identifier时才会上报解构模式等节点会被跳过。源码级解析规则的执行机制规则的全部判定逻辑集中在 lib/rules/init-declarations.js 的create函数中核心是VariableDeclaration:exit遍历器。每个声明节点会依次经过三个判断是否豁免node.declare或位于declare namespace内部 → 跳过是否已初始化调用isInitialized非 for 循环场景看node.init是否存在for 循环场景看声明是否位于循环头部的init/left位置是否命中模式always且未初始化 → 报initializednever且非const/using/await using、已初始化、且未命中ignoreForLoopInit→ 报notInitialized。上报时使用context.report携带messageId与变量名idName最终展示为如Variable foo should be initialized on declaration.的人类可读信息。规则的完整行为由 tests/lib/rules/init-declarations.js 中的RuleTester用例守护JavaScript 用例覆盖了多声明混写如var foo, bar false, baz;只报告foo与baz、函数作用域、for 循环三类变体TypeScript 用例通过typescript-eslint/parser驱动则覆盖了declare、namespace、嵌套 namespace、interface、类内部变量、类型别名等场景。值得一提的是规则的元信息中docs.recommended: false意味着它属于团队可选风格规则但frozen: true保证了即使未来 ESLint 大版本迭代其行为也不会悄然改变。规则通过 lib/rules/index.js 注册到内置规则集合同时被 eslint-all 配置 收录init-declarations: error也就是说开启全部规则时它会被激活。关联规则与 no-unassigned-vars 的分工本规则在文档中声明了关联规则no-unassigned-vars见 规则元数据 的related_rules字段。两者视角互补init-declarations关注风格变量应在哪里初始化声明时 vs 声明后与变量是否真的被使用无关no-unassigned-vars关注正确性let/var变量被读取却从未被赋值导致其永远为undefined几乎一定是编程错误见 no-unassigned-vars 文档 与 源码。例如let status; if (status ready) {...}中status从未被赋值no-unassigned-vars会判定这是 bug而let status; status check(); console.log(status);这类先声明后赋值的写法no-unassigned-vars不会报错但init-declarations: [error, always]会要求你把声明合并为let status check();。no-unassigned-vars属于recommended: true的问题类规则且对declare声明、const、using、await using等同样有豁免处理两者搭配使用可以同时覆盖一致性与潜在 bug两个维度。何时不该使用本规则官方文档给出的建议是当你不在意变量的初始化方式时可以关闭此规则。具体而言以下团队场景可以放心停用代码库中两种风格并存且没有统一意图强行约束反而引发大量与逻辑无关的改动噪音项目大量使用声明后条件赋值模式如错误处理变量、惰性初始化always模式会频繁误伤never模式又可能不适配已有no-unassigned-vars承担正确性检查团队更倾向于让声明风格保持自由。总结init-declarations是一把简单但精准的风格规尺always默认强制声明即初始化never强制先声明后赋值ignoreForLoopInit为 for 循环提供豁免它对var、let、const、using、await using五种声明类型差异对待并对 TypeScript 的declare、declare namespace声明网开一面。配合 规则文档、源码实现 与 完整测试 查阅你可以在团队中快速评估并落地这一风格约束。【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
