Next.js 项目 中 noUnusedLocals 配错会引发哪些 TypeScript 问题
我在 Next.js 项目中打开了 TypeScript 的 noUnusedLocals，结果很多文件开始提示错误。这个配置到底会检查什么，为什么会影响到正常开发？
noUnusedLocals 会把未使用的局部变量和导入直接标记为错误
noUnusedLocals 会检查文件中的局部变量、函数参数以外的未使用项，常见表现是未使用的 import、变量、常量、函数声明等被 TypeScript 判定为问题。在 Next.js 项目里，页面、组件、工具函数经常会因为重构、条件分支变化或临时调试留下未使用代码，从而触发报错。这个配置本身不会破坏运行，但会让编译和类型检查阶段变得更严格，导致构建失败或开发体验受影响。
我发现有些变量明明是为了后续逻辑准备的，TypeScript 还是提示未使用。Next.js 场景下，哪些写法更容易被 noUnusedLocals 误判或触发报错？
条件渲染、类型声明和仅用于约束的代码最容易触发
在 Next.js 项目中，某些变量只是为条件渲染、类型推断或调试而存在，如果没有在实际代码路径中被引用，就会被 noUnusedLocals 识别为未使用。比如导入了一个组件但没渲染、定义了临时对象却没有参与返回值、保留了旧版接口字段但未再消费，都会引发报错。对于仅用于类型层面的内容，也可能因为写法不当被识别为“值未使用”。
如果 noUnusedLocals 设置得太严格，或者配置位置不对，会不会导致 Next.js 项目无法正常构建、上线失败，甚至影响 CI/CD？
会，尤其在构建阶段和持续集成中更明显
如果 noUnusedLocals 被开启，项目里存在大量未使用变量或导入，TypeScript 检查就可能直接失败，进而影响 next build、CI 流程和部署。配置错误还可能让某些文件在本地看似正常，但在团队环境中因类型检查策略不同而出现不一致的问题。对于依赖自动化发布的 Next.js 项目，这类错误会放大为构建阻断、流水线失败或审核无法通过。
我不确定现在的报错是 TypeScript 配置写错了，还是代码里确实有没清理干净的内容。应该怎么区分这两种情况？
先看报错位置和触发范围，再检查 tsconfig 与实际代码
如果报错集中在少数文件，通常是代码中确实存在未使用的变量、导入或声明。如果报错范围很广，甚至包含你认为本应合法的写法，就要检查 tsconfig 的继承关系、Next.js 项目是否存在多个类型配置文件，以及 noUnusedLocals 是否和其他严格选项一起开启后产生连锁影响。可以通过临时关闭该项、逐步恢复配置、对比报错变化来定位是配置问题还是代码清理问题。