企业官网建设流程全解析

ESLint function-paren-newline 规则详解：强制函数括号内换行一致性

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint

function-paren-newline 是 ESLint 内置布局（layout）类规则，用于在函数形参或实参的括号内部强制执行一致、统一的换行风格——它同时覆盖函数声明、函数表达式、箭头函数、函数调用、new表达式以及动态import()这六类语法节点。读完本文，你将掌握该规则全部 5 种字符串选项与minItems对象选项的语义差异、每种选项下正确与错误代码的判定标准、底层源码的判定算法，以及它在当前仓库中被弃用的背景与迁移路径。

规则简介与适用场景

许多风格指南要求或禁止在函数括号内部出现换行，function-paren-newline正是为这类需求而生：它检查函数形参（parameters）和调用实参（arguments）两侧括号内侧的换行情况，并强制整个括号对保持一致的书写风格。

从 源码定义 可以看到，该规则：

• type为"layout"，属于纯排版类规则，不影响代码语义；
• fixable: "whitespace"，意味着绝大多数问题都可以通过--fix自动修复；
• recommended: false，不包含在 ESLint 的推荐配置中，需要用户显式开启。

规则实际检查的 AST 节点类型（见 getParenTokens 与监听器实现）包括：

对于没有括号的箭头函数（如foo => {}）以及没有实参的new Foo，规则会直接跳过（源码中通过getParenTokens返回null处理，见 lib/rules/function-paren-newline.js#L251-L332）。

选项详解：字符串与对象两种形态

该规则只有一个选项，可以是字符串也可以是对象（对应源码 schema 定义）。字符串选项取值为枚举："always"、"never"、"multiline"、"multiline-arguments"、"consistent"；对象选项则形如{ "minItems": value }。

选项如何映射为源码中的阈值

理解选项内部机制，有助于理解边界行为。在 create 函数 中，规则把选项归一化为一个minItems阈值：

const rawOption = context.options[0] || "multiline"; if (typeof rawOption === "object") { minItems = rawOption.minItems; } else if (rawOption === "always") { minItems = 0; // 数量 >= 0 恒成立 ⇒ 永远要求换行 } else if (rawOption === "never") { minItems = Infinity; // 数量 >= Infinity 恒不成立 ⇒ 永远禁止换行 } else { minItems = null; // multiline / multiline-arguments / consistent 走专用分支 }

也就是说，"always"等价于{ "minItems": 0 }，"never"等价于{ "minItems": Infinity }，而"multiline"、"multiline-arguments"、"consistent"三个选项则由shouldHaveNewlines中的专用逻辑处理（见 lib/rules/function-paren-newline.js#L116-L132）：

• multiline/multiline-arguments：只要相邻两个形参/实参不在同一行（element.loc.end.line !== elements[index + 1].loc.start.line），就要求括号内换行；
• multiline-arguments的额外分支：当elements.length === 1（只有一个参数）时，括号内是否换行完全跟随左括号当前的状态hasLeftNewline，因此单个参数时两种风格都合法；
• consistent：括号内是否换行直接取hasLeftNewline（左括号后是否已有换行），即把右侧与左侧对齐。

配置示例

{ "rules": { "function-paren-newline": ["error", "never"] } }

{ "rules": { "function-paren-newline": ["error", { "minItems": 3 }] } }

对象选项的 schema 还声明了约束：minItems必须是非负整数（type: "integer", minimum: 0），且不允许出现额外属性（additionalProperties: false），否则会触发配置校验错误（见 lib/rules/function-paren-newline.js#L65-L74）。

选项 "always"：所有括号内强制换行

开启"always"后，只要函数声明、表达式、箭头函数或调用出现在括号中，(之后与)之前都必须有换行。

不正确的代码（"always"）：

/* eslint function-paren-newline: ["error", "always"] */ function foo(bar, baz) {} var qux = function(bar, baz) {}; var qux = (bar, baz) => {}; foo(bar, baz);

正确的代码（"always"）：

/* eslint function-paren-newline: ["error", "always"] */ function foo( bar, baz ) {} var qux = function( bar, baz ) {}; var qux = ( bar, baz ) => {}; foo( bar, baz );

注意在"always"下，括号内的形参之间不需要换行（如bar, baz写在同一行是允许的），规则只约束左右括号的内侧。这对应源码中validateParens只检查(后与)前的换行、而参数间的换行仅在multiline-arguments下才由validateArguments额外检查（见 lib/rules/function-paren-newline.js#L140-L241）。

选项 "never"：所有括号内禁止换行

开启"never"后，函数括号内侧出现任何换行都会报错。

不正确的代码（"never"）：

/* eslint function-paren-newline: ["error", "never"] */ function foo( bar, baz ) {} var qux = function( bar, baz ) {}; var qux = ( bar, baz ) => {}; foo( bar, baz );

正确的代码（"never"）：

/* eslint function-paren-newline: ["error", "never"] */ function foo(bar, baz) {} function qux(bar, baz) {} var foobar = function(bar, baz) {}; var foobar = (bar, baz) => {}; foo(bar, baz); foo(bar, baz);

一个值得注意的细节：在"never"下，function qux(bar,\n baz) {}是合法的——规则只检查括号内侧（(与第一个形参之间、最后一个形参与)之间）没有换行，参数之间是否换行并不属于"never"的管辖范围（只有在multiline-arguments选项下参数间换行才会被检查）。

默认选项 "multiline"：跟随参数是否跨行

"multiline"是该规则的默认选项（context.options[0] || "multiline"），核心思想是保持代码原有的多行/单行意图：只要任意两个形参/实参之间存在换行，就要求括号内部也换行；如果所有参数都在同一行，则禁止括号内换行。

不正确的代码（默认"multiline"）：

/* eslint function-paren-newline: ["error", "multiline"] */ function foo(bar, baz ) {} var qux = function( bar, baz ) {}; var qux = ( bar, baz) => {}; foo(bar, baz); foo( function() { return baz; } );

最后一条foo(\n function() {...}\n)之所以不正确，是因为单个实参内部的函数体虽然是多行的，但规则统计的是形参/实参元素之间的换行（相邻元素的loc.end.line与loc.start.line），单个实参不构成"参数之间有换行"，因此此时括号内侧不应换行。

正确的代码（默认"multiline"）：

/* eslint function-paren-newline: ["error", "multiline"] */ function foo(bar, baz) {} var foobar = function( bar, baz ) {}; var foobar = (bar, baz) => {}; foo(bar, baz, qux); foo( bar, baz, qux ); foo(function() { return baz; });

注意foo(function() {...})在这里是正确的：参数只有一项且与其他参数没有"之间换行"，因此括号内不换行也是合规的。

选项 "consistent"：括号两侧换行状态必须一致

"consistent"关注的是每一对括号自身的对称性：如果(后有换行而)前没有（或相反），就报告错误。它不像multiline那样关心参数是否跨行，只看左右括号的内侧状态是否一致。

不正确的代码（"consistent"）：

/* eslint function-paren-newline: ["error", "consistent"] */ function foo(bar, baz ) {} var qux = function(bar, baz ) {}; var qux = ( bar, baz) => {}; foo( bar, baz); foo( function() { return baz; });

正确的代码（"consistent"）：

/* eslint function-paren-newline: ["error", "consistent"] */ function foo(bar, baz) {} var qux = function(bar, baz) {}; var qux = ( bar, baz ) => {}; foo( bar, baz ); foo( function() { return baz; } );

可以看到，在"consistent"下function foo(bar,\n baz)是合法的（左侧(后无换行、右侧)前也无换行，两侧一致），而foo(\n bar, baz)同样合法（两侧都有换行）。判断依据正是源码中的return hasLeftNewline;——以左括号的状态为准对齐右括号（lib/rules/function-paren-newline.js#L128-L130）。

选项 "multiline-arguments"：multiline 的灵活变体

"multiline-arguments"在multiline的基础上放宽了"单个参数"的场景：当括号内只有一个形参/实参时，无论括号内是否换行都被允许（此时跟随左括号当前状态即可）；当存在多个参数且参数间存在换行时，要求括号内换行。

不正确的代码（"multiline-arguments"）：

/* eslint function-paren-newline: ["error", "multiline-arguments"] */ function foo(bar, baz ) {} var foobar = function(bar, baz ) {}; var foobar = ( bar, baz) => {}; foo( bar, baz); foo( bar, qux, baz );

最后一条foo(\n bar, qux,\n baz\n)是不正确的，因为参数之间存在换行（bar, qux与baz分行），此时规则要求参数之间也要换行——这正是multiline-arguments独有的validateArguments检查，它会遍历相邻参数对，若参数间无换行则报告expectedBetween错误（见 lib/rules/function-paren-newline.js#L218-L241）。

正确的代码（"multiline-arguments"）：

/* eslint function-paren-newline: ["error", "multiline-arguments"] */ function foo( bar, baz ) {} var qux = function(bar, baz) {}; var qux = ( bar ) => {}; foo( function() { return baz; } );

注意var qux = (\n bar\n) => {}是正确的：只有一个形参时，括号内换行是被允许的（对应源码中elements.length === 1时返回hasLeftNewline的分支，lib/rules/function-paren-newline.js#L117-L119）。这也是它与默认"multiline"最直观的区别：默认模式下单个参数多行书写（如foo(\n function() {...}\n)）会被判错，而multiline-arguments不会。

对象选项 { "minItems": value }：按参数数量决定换行

当选项为对象{ "minItems": value }时，规则按形参/实参的数量决定是否需要括号内换行：数量达到value时要求换行，否则禁止换行。该选项适合"参数多了再展开、参数少就单行"的团队规范。

以{ "minItems": 3 }为例（参数数量 ≥ 3 时才展开换行）：

不正确的代码：

/* eslint function-paren-newline: ["error", { "minItems": 3 }] */ function foo( bar, baz ) {} function foobar(bar, baz, qux) {} var barbaz = function( bar, baz ) {}; var barbaz = ( bar, baz ) => {}; foo( bar, baz );

function foobar(bar, baz, qux)不正确，是因为 3 个参数达到了minItems阈值，必须换行；其余几条则是参数不足 3 个却换行了。

正确的代码：

/* eslint function-paren-newline: ["error", { "minItems": 3 }] */ function foo(bar, baz) {} var foobar = function( bar, baz, qux ) {}; var foobar = ( bar, baz, qux ) => {}; foo(bar, baz); foo( bar, baz, qux );

注意在minItems模式下，达到阈值后只要求括号内侧换行，参数之间仍可保持同一行（如var foobar = (\n bar, baz, qux\n) => {}）。由于"always"等价于{ "minItems": 0 }、"never"等价于{ "minItems": Infinity }，熟悉这个对象选项之后，字符串选项的内部行为也就一目了然了。

自动修复与修复限制

该规则标记为fixable: "whitespace"，因此开启后运行eslint --fix可以自动修正绝大多数换行问题。规则产生的五类报告消息（见 messages 定义）为：

• expectedAfter：(后缺少换行，修复方式是在左括号后插入\n；
• expectedBefore：)前缺少换行，修复方式是在右括号前插入\n；
• unexpectedAfter：(后出现多余换行，修复方式是删除(与下一个 token 之间的空白；
• unexpectedBefore：)前出现多余换行，修复方式是删除最后一个 token 与)之间的空白；
• expectedBetween：参数之间缺少换行（仅multiline-arguments触发），修复方式是在下一个参数前插入\n。

但有一个重要的修复限制：如果括号与第一个/最后一个元素之间存在注释，规则会放弃自动修复（返回null），以避免破坏注释位置。源码中对此有明确处理——(与首个 token 之间的文本trim()后非空则跳过修复，)前同理（见 lib/rules/function-paren-newline.js#L159-L173 与 lib/rules/function-paren-newline.js#L187-L200）。因此，遇到"括号与参数间夹着注释"的代码，需要手动调整换行。

源码判定流程一览

结合 lib/rules/function-paren-newline.js 的完整实现，该规则对每个命中节点的处理分三步：

1. 定位括号 token：getParenTokens根据节点类型（CallExpression/NewExpression取 callee 后的开括号与末尾闭括号，函数类取第一个开括号与最后一个参数后的闭括号，箭头函数跳过async关键字，ImportExpression取首尾 token），并处理无括号情况返回null（lib/rules/function-paren-newline.js#L251-L332）；
2. 判定期望状态：shouldHaveNewlines依据选项计算"括号内是否应当换行"（lib/rules/function-paren-newline.js#L116-L132）；
3. 比对并报告/修复：validateParens分别检查(后与)前的实际换行状态，与期望不一致时按对应 messageId 报告，必要时附带修复器；multiline-arguments还会额外调用validateArguments检查参数间的换行（lib/rules/function-paren-newline.js#L140-L241）。

其中换行状态的判断基于 token 位置：astUtils.isTokenOnSameLine(leftParen, tokenAfterLeftParen)为假即视为存在换行。

仓库中配套的规则测试位于 tests/lib/rules/function-paren-newline.js，共 1522 行，覆盖了全部选项在valid/invalid两组用例下的行为，包括async箭头函数、动态import()、new Foo、无括号箭头函数、模板字符串实参等边界场景，是验证上述规则语义的最佳参考。

弃用说明与迁移建议

需要特别提醒：该规则已在ESLint v8.53.0中标记为弃用（deprecated），计划可用至v11.0.0。弃用原因是 ESLint 团队将排版类（formatting）规则逐步移出核心库，交由 ESLint Stylistic 社区项目维护（见 lib/rules/function-paren-newline.js#L20-L41 中的弃用元数据）。

迁移方式：若项目仍使用旧版本可继续沿用本文配置；若使用 ESLint v9+ 并需要长期维护，建议改用@stylistic/eslint-plugin中同名的function-paren-newline规则，选项语义保持一致，配置方式如下：

// eslint.config.js（flat config） import stylistic from "@stylistic/eslint-plugin"; export default [ { plugins: { "@stylistic": stylistic }, rules: { "@stylistic/function-paren-newline": ["error", "multiline"] } } ];

如果你不想强制函数括号内的换行风格，则不要开启本规则——尤其是当项目中既有全单行写法、又有"长参数列表手动换行"的混合风格时，该规则反而会造成额外噪音。此时更合适的做法是保持现状或改用整体格式化工具（如 Prettier）统一排版。

小结

function-paren-newline通过一个选项覆盖了从"永远换行"到"永远不换行"的完整策略谱系："always"与"never"是两个极端，"multiline"（默认）与"multiline-arguments"根据参数是否跨行自适应，"consistent"强调括号两侧对称，而{ "minItems": N }则按参数数量决定阈值。理解其底层的minItems归一化与"仅检查括号内侧"的判定规则，就能准确预判任何代码风格下该规则的行为；在最新项目中，请优先考虑迁移到@stylistic/eslint-plugin以获得持续维护。

【免费下载链接】eslintFind and fix problems in your JavaScript code.项目地址: https://gitcode.com/GitHub_Trending/es/eslint