如何用Qodana修复常见TypeScript问题

修复常见 TypeScript 问题 | Qodana 博客

团队代码质量平台

如何使用 Qodana 修复常见 TypeScript 问题

2026年6月1日

大多数 TypeScript 项目已经使用 ESLint 和 @typescript-eslint 进行代码检查。这可以覆盖很多问题：显式的 any 类型、未处理的 Promise、非空断言等。如果您的代码检查配置完善，就能在代码审查前于编辑器中捕获明显的错误。

ESLint 规则无法跨文件检测问题。每个规则仅在单个文件的作用域内运行，这意味着 ESLint 无法告知您代码库中某个导出是否在所有地方都未被使用，也无法检测到某个文件中的 any 类型值是否导致了相隔五层文件之外的不安全假设，或者两个组件是否独立实现了相同的逻辑。这正是 Qodana 所填补的空白。

以下是五个值得解决的 TypeScript 问题，按 ESLint 能处理的部分和其无法覆盖的范围进行分类。

代码库中隐式 `any` 类型的传播

ESLint 的 no-explicit-any 规则会捕获显式使用 any 的地方。但它无法跟踪 any 从外部来源（如 response.json()、无类型定义的第三方库或未声明类型的导入）进入代码库时的情况。一旦外部引入的 any 类型值进入代码，它会通过属性访问和函数调用无声地传播。ESLint 的 no-unsafe-* 规则可以捕获此类问题，但前提是您使用了 @typescript-eslint/recommended-type-checked 配置，这需要启用类型感知的代码检查，而该配置远不如标准推荐配置常见。

async function getUser(id: string) {
  const res = await fetch(`/api/users/${id}`);
  const data = await res.json(); // type: any

  return data.profile.name; // 没有错误——但若 profile 为 undefined 则会崩溃
}

response.json() 在标准库中返回 any 类型。下游所有代码都未声明类型。编译器接受任何属性名和方法调用。问题在运行时才会暴露。Qodana 会跟踪 any 类型在程序中跨文件的传播。当 any 类型的值到达某个代码路径，而该路径假设了特定结构时，即使这个路径距离 any 进入代码库的源头相隔多个函数调用，Qodana 也会标记出这种不一致。

添加 UserResponse 接口并不能解决这个问题，它只是将错误更接近崩溃点。应该对边界进行类型声明：

interface UserResponse {
  profile: { name: string };
}

const data: UserResponse = await res.json();

如果 API 响应结构发生变化，类型错误会在编译时暴露。

将非空断言用作捷径

ESLint 的 no-non-null-assertion 规则会统一标记所有 ! 运算符。这确实有效，但许多团队会禁用该规则或添加宽泛的例外，因为合法的用法（如运行时检查后）与危险的用法会被一并标记。这导致信号过于嘈杂，规则被关闭，问题也从视野中消失。

function renderUser(user: User | null) {
  return `Hello, ${user!.name}`; // 若 user 为 null 则运行时崩溃
}

const button = document.querySelector(".submit-btn");
button!.addEventListener("click", handleSubmit); // 若元素不存在则崩溃

两个示例在编译时都不会报错，但在可预测的条件下会崩溃。! 通常被用来掩盖类型错误，而没有解决根本问题。

正确的做法是处理 null 的情况：

function renderUser(user: User | null) {
  if (!user) return "Guest";
  return `Hello, ${user.name}`;
}

const button = document.querySelector(".submit-btn");
if (button) {
  button.addEventListener("click", handleSubmit);
}

Qodana 会在报告中将非空断言单独归类。并非所有 ! 都是错误的，但将它们集中展示有助于区分合法用法和捷径，而无需在“规则过于嘈杂”和“完全不启用规则”之间做出选择。

未处理的 Promise

ESLint 的 @typescript-eslint/no-floating-promises 规则确实有效，但它是基于类型感知的规则。它需要在 ESLint 配置中通过 parserOptions.project 启用 TypeScript 类型检查。在未配置该选项的项目中，或仅对部分代码库配置的项目中，该规则在未覆盖的文件中会静默失效。

async function onSubmit(data: FormData) {
  saveToDatabase(data); // Promise<void>, 未使用 await
  router.push("/success"); // 在保存完成前执行
}

TypeScript 会接受这种写法而不会报错。调用异步函数而不使用 await 被视为有效语法，返回值会被丢弃。然而，这种行为是错误的：用户会在保存完成前看到成功页面，且任何数据库错误都会被静默吞掉。

async function onSubmit(data: FormData) {
  await saveToDatabase(data);
  router.push("/success");
}

Qodana 的分析默认对整个项目进行类型感知，无需单独配置 ESLint 的 TypeScript 集成。无论项目中 ESLint 的配置结构如何，未处理的 Promise 都会被一致地标记。

未使用的导出

tsconfig 中的 noUnusedLocals 会捕获文件内未使用的变量。导出的符号被设计为排除在外。从编译器的角度来看，外部文件可能导入它们。ESLint 的 eslint-plugin-import 提供了 import/no-unused-modules 规则，可以检测此类问题，但每次代码检查都需要扫描整个依赖图，对大型代码库会产生显著的性能开销。对于大多数项目来说，保持该规则启用并不实际。

// utils/format.ts export function formatCurrency(n: number): string { ... } export function formatPercent(n: number): string { ... } // 已移除功能，仍保留在代码中 export function formatBytes(n: number): string { ... } // 从未被导入使用 这三个函数在检查时均未产生警告，但 formatPercent 和 formatBytes 实际是死代码。它们增加了维护负担，拖慢重构速度，并误导开发者认为导出的符号正在被使用。

检测这类问题需要对整个项目进行分析。Qodana 会构建整个代码库的引用图，追踪每个导入和重新导出关系。仅作为源代码出现、从未被其他模块导入的符号会被标记。tsc 和 ESLint 都无法实现这种分析。

跨文件重复逻辑

ESLint 本身不支持原生的重复逻辑检测。虽然存在 jscpd 等独立工具，但它们不属于你的 linting 流程。这意味着需要额外的配置、维护工作和记忆负担。结果就是，组件或工具文件之间的逻辑复制会不断累积，却无人察觉。

// components/UserCard.tsx function formatUserName(user: User): string { if (!user.firstName && !user.lastName) return "Anonymous"; return [user.firstName, user.lastName].filter(Boolean).join(" "); } // components/UserBadge.tsx function getDisplayName(user: User): string { if (!user.firstName && !user.lastName) return "Anonymous"; return [user.firstName, user.lastName].filter(Boolean).join(" "); } 这不是风格问题。这意味着需要在多个位置应用相同的 bug 修复，而当修复未被同步时，两处代码的行为会悄然产生差异。

Qodana 在检测类型问题和未使用导出的同时，也会检测跨文件重复代码。当这些发现与其他问题一起出现在报告中时，比单独运行的工具更难被忽视。

为 TypeScript 项目配置 Qodana

上述所有五个问题在 Qodana 的 JavaScript/TypeScript 项目默认配置中均可检测到。以下是启动项目的最小配置：

version: "1.0" linter: jetbrains/qodana-js:2026.1 bootstrap: npm ci profile: