GitHub Actions执行pnpm build报TS2322错误，本地构建正常

问题详情 #

在GitHub Actions环境执行pnpm build时出现TypeScript编译错误，但本地执行相同命令无异常。

错误信息 #

Error: ../../packages/hooks/use-forward-ref/index.ts:20:5 - error TS2322: Type '(el: T) => void' is not assignable to type 'ForwardRefSetter'.
Types of parameters 'el' and 'el' are incompatible.
Type 'T' is not assignable to type 'T'. Two different types with this name exist, but they are unrelated.
'T' could be instantiated with an arbitrary type which could be unrelated to 'T'.

错误指向代码第20行：setForwardRef,

解决方案 #

• 同步TypeScript版本：在package.json中锁定typescript的精确版本（比如"typescript": "~5.1.6"），确保本地与GitHub Actions环境使用完全一致的TS版本，避免版本差异导致的类型推断逻辑不同。
• 清理CI依赖缓存：在GitHub Actions的构建流程中，添加依赖缓存清理步骤，执行pnpm store prune后再重新安装依赖；或者使用缓存动作时，正确配置缓存key，确保缓存的依赖与当前lockfile匹配。
• 修复泛型参数冲突：检查use-forward-ref/index.ts中的泛型定义，确认是否存在同名泛型T的作用域冲突（比如在嵌套函数或导入模块中重复定义了T）。可以将泛型参数重命名为更具辨识度的名称（如TElement），消除类型推断的歧义。
• 统一pnpm配置：确保本地与CI环境的.npmrc配置一致，尤其是hoist、public-hoist-pattern等与依赖解析相关的设置，避免CI环境下类型文件的解析路径与本地不一致。
• 强制重新安装依赖：在CI步骤中执行pnpm install --force，强制依赖完全按照pnpm-lock.yaml安装，杜绝依赖版本不一致的问题。

内容的提问来源于stack exchange，提问作者Sima thief