解决 Next.js 中 “no-explicit-any” ESLint 错误的指南

引言

no explicit any

TypeScript 的 any 类型会绕过编译期检查，削弱静态类型带来的安全性。为强化类型安全，ESLint 规则 @typescript-eslint/no-explicit-any 会标记任何对 any 的使用。在使用 TS 的 Next.js 应用中，你可能会遇到如下错误：

./src/lib/types/resource.ts
24:14  Error: Unexpected any. Specify a different type.  @typescript-eslint/no-explicit-any
28:11  Error: Unexpected any. Specify a different type.  @typescript-eslint/no-explicit-any
30:14  Error: Unexpected any. Specify a different type.  @typescript-eslint/no-explicit-any

info  - Need to disable some ESLint rules? Learn more here: https://nextjs.org/docs/app/api-reference/config/eslint#disabling-rules

// 触发 no-explicit-any 的示例：
function fetchData(url: string): Promise<any> {
  return fetch(url).then(res => res.json());
}

不受控地使用 any 容易引发运行时 bug，让接口语义变得含糊，降低代码可维护性。本文将优先介绍如何在 Next.js 中配置 ESLint 来“控制或关闭”该规则，并给出更安全的替代方案。

根因解析

`no-explicit-any` 到底限制了什么

该规则会阻止显式的 : any 注解以及隐式回退为 any 的情况。它敦促你始终声明更精确的类型，或使用更安全的 unknown 等替代品。

Next.js 默认的 TypeScript ESLint 配置

Next.js 默认扩展了 plugin:@typescript-eslint/recommended。该预设包含：

"rules": {
  "@typescript-eslint/no-explicit-any": "error"
}

因此，只要出现 any（无论显式还是推断得到），在开发或构建时都会触发 ESLint 报错。

常见触发场景

快速原型：为图快而临时使用 any。
三方数据：缺少类型定义的 JSON 或 API 响应常以 any 开始。
渐进迁移：给存量 Next.js 代码补 TS 时，容易出现大量 any。

推荐方案：在 Next.js 中配置 ESLint

全局调整 `.eslintrc.js`

若希望在全局放宽或关闭该规则，修改 .eslintrc.js：

module.exports = {
  extends: ["next/core-web-vitals", "plugin:@typescript-eslint/recommended"],
  rules: {
    "@typescript-eslint/no-explicit-any": "off", // 关闭规则
    // 或仅改为告警：
    // "@typescript-eslint/no-explicit-any": "warn",
  },
};

通过 `next.config.js` 调整

若仅希望在“生产构建”时忽略 ESLint 错误，可修改 next.config.js：

module.exports = {
  eslint: {
    ignoreDuringBuilds: true, // skips all ESLint errors at build time
  },
};

⚠️ 这会在构建时静默所有 ESLint 错误；请谨慎使用。

按文件或代码块临时关闭

若只需定点关闭，可添加 ESLint 内联注释：

/* eslint-disable @typescript-eslint/no-explicit-any */
function legacyHandler(payload: any) {
  // ...具体实现
}
/* eslint-enable @typescript-eslint/no-explicit-any */

或仅对单行关闭：

const data: any = fetchSomething(); // eslint-disable-line @typescript-eslint/no-explicit-any

TypeScript 层面的相关配置

如果你维护了单独的 tsconfig.json 用于检查，请确保包含：

{
  "compilerOptions": {
    "noImplicitAny": true, // 在编译期捕获隐式 any
    // 以及其它严格标志...
  }
}

并让 ESLint 与之对齐：

// .eslintrc.js
parserOptions: {
  project: ['./tsconfig.json'],
},

替代方案

当你希望保持更严格的类型安全时，优先考虑以下写法，而不是直接关闭规则：

使用 unknown：在使用前强制类型收窄与检查。

async function fetchData(): Promise<unknown> {
  const res = await fetch('/api/data');
  return res.json();
}

定义接口（Interface）：为 API 响应显式建模。

interface User { id: number; name: string; }
async function getUser(): Promise<User> { /* ... */ }

使用泛型（Generics）：让工具函数在类型上更可复用。
```
function fetchTyped<T>(url: string): Promise<T> { /* ... */ }
```

其他实用权衡

渐进式类型迁移（`// @ts-ignore`）

在偶发场景下，可临时忽略 TS 报错：

// @ts-ignore
const result = legacyFunction();

类型断言（Type Assertions）

在你确信类型时，断言为更具体的类型：

const value = (obj as MyType).property;

针对特定文件添加 ESLint overrides

例如在测试或 Mock 文件里关闭该规则：

module.exports = {
  overrides: [
    {
      files: ['**/*.test.ts', '**/*.spec.ts'],
      rules: {
        '@typescript-eslint/no-explicit-any': 'off',
      },
    },
  ],
};

总结与参考

方案	优点	缺点
全局关闭 ESLint 规则	见效最快，构建与开发均无报错噪音	所有 explicit-any 问题都会被掩盖
使用 `unknown`	保留类型安全，强制显式检查	需要额外的类型收窄/检查样板代码
定义接口与使用泛型	类型更强、自文档化代码	需要一定的前期建模与维护成本
局部关闭或使用 overrides	颗粒度更细，可按需抑制	指令分散在代码中，可能影响可读性

引言