Skip to main content

ban-ts-comment

禁止 @ts-<directive> 注释或要求指令后有描述.

✅

在 ESLint 配置 中扩展"plugin:@typescript-eslint/recommended" 可启用此规则。

💡

此规则报告的一些问题可以通过编辑器 建议 手动修复。

TypeScript 提供了几个指令注释，可用于改变它处理文件的方式。使用这些来抑制 TypeScript 编译器错误会降低 TypeScript 的整体效率。相反，通常最好纠正代码类型，以使指令变得不必要。

¥TypeScript provides several directive comments that can be used to alter how it processes files. Using these to suppress TypeScript compiler errors reduces the effectiveness of TypeScript overall. Instead, it's generally better to correct the types of code, to make directives unnecessary.

TypeScript 支持的指令注释有：

¥The directive comments supported by TypeScript are:

// @ts-expect-error
// @ts-ignore
// @ts-nocheck
// @ts-check

此规则查找对 的调用，并报告是否传递和断言了初始值。

¥This rule lets you set which directive comments you want to allow in your codebase.

eslint.config.mjs
export default tseslint.config({
  rules: {
    "@typescript-eslint/ban-ts-comment": "error"
  }
});

在线运行试试这个规则 ↗

选项​

This rule accepts the following options, and has more strict settings in the strict config.

type DirectiveConfigSchema =
  | 'allow-with-description'
  | {
      descriptionFormat?: string;
    }
  | boolean;

type Options = [
  {
    'ts-check'?: DirectiveConfigSchema;
    'ts-expect-error'?: DirectiveConfigSchema;
    'ts-ignore'?: DirectiveConfigSchema;
    'ts-nocheck'?: DirectiveConfigSchema;
    /** 启用 `allow-with-description` 时描述的最小字符长度。 */
    minimumDescriptionLength?: number;
  },
];

const defaultOptionsRecommended: Options = [
  {
    minimumDescriptionLength: 3,
    'ts-check': false,
    'ts-expect-error': 'allow-with-description',
    'ts-ignore': true,
    'ts-nocheck': true,
  },
];

// These options are merged on top of the recommended defaults
const defaultOptionsStrict: Options = [{ minimumDescriptionLength: 10 }];

¥Options

默认情况下，只允许 @ts-check，因为它启用而不是抑制错误。

¥By default, only @ts-check is allowed, as it enables rather than suppresses errors.

ts-expect-error、ts-ignore、ts-nocheck、ts-check 指令​

¥ts-expect-error, ts-ignore, ts-nocheck, ts-check directives

特定指令的 true 值意味着如果此规则发现该指令的任何用法，它将报告。

¥A value of true for a particular directive means that this rule will report if it finds any usage of said directive.

if (false) {
  // @ts-ignore: Unreachable code error
  console.log('hello');
}
if (false) {
  /* @ts-ignore: Unreachable code error */
  console.log('hello');
}
Open in Playground

allow-with-description​

特定指令的 'allow-with-description' 值意味着如果此规则发现指令之后没有描述的指令（在同一行），它将报告。

¥A value of 'allow-with-description' for a particular directive means that this rule will report if it finds a directive that does not have a description following the directive (on the same line).

例如，使用 { 'ts-expect-error': 'allow-with-description' }：

¥For example, with { 'ts-expect-error': 'allow-with-description' }:

if (false) {
  // @ts-expect-error
  console.log('hello');
}
if (false) {
  /* @ts-expect-error */
  console.log('hello');
}
Open in Playground

descriptionFormat​

对于每个指令类型，你可以以正则表达式的形式指定自定义格式。仅允许与模式匹配的描述。

¥For each directive type, you can specify a custom format in the form of a regular expression. Only description that matches the pattern will be allowed.

例如，使用 { 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }：

¥For example, with { 'ts-expect-error': { descriptionFormat: '^: TS\\d+ because .+$' } }:

// @ts-expect-error: the library definition is wrong
const a = doSomething('hello');
Open in Playground

minimumDescriptionLength​

当使用 allow-with-description 选项作为指令时，使用 minimumDescriptionLength 设置描述的最小长度。

¥Use minimumDescriptionLength to set a minimum length for descriptions when using the allow-with-description option for a directive.

例如，对于 { 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 }，以下模式为：

¥For example, with { 'ts-expect-error': 'allow-with-description', minimumDescriptionLength: 10 } the following pattern is:

if (false) {
  // @ts-expect-error: TODO
  console.log('hello');
}
Open in Playground

何时不使用它​

¥When Not To Use It

如果你的项目或其依赖在设计时没有考虑到强类型安全性，那么始终遵守正确的 TypeScript 语义可能会很困难。你可以考虑在这些特定情况下使用 ESLint 禁用注释，而不是完全禁用此规则。

¥If your project or its dependencies were not architected with strong type safety in mind, it can be difficult to always adhere to proper TypeScript semantics. You might consider using ESLint disable comments for those specific situations instead of completely disabling this rule.

进一步阅读​

¥Further Reading

资源​