Nuxt 2.x升级后构建报错：无法识别this.$refs及相关问题求助

• 环境：Nuxt ~2.17.0、Node 18.20.5
• 执行yarn dev或yarn build时，多数.vue文件触发TS2304错误，提示Cannot find name 'this'，错误示例：

TS2304: Cannot find name 'this'.
   369 |   }
   370 |
>371 |   handleKeyDownEnter(refsItem: keyof typeof this.$refs) {
       |                                             ^^^^
   372 |     return () => {
   373 |       this.$refs[refsItem]?.handleFocus()
   374 |     }

• VS Code（TypeScript 5.7.2）编写代码时无报错
• Node 16.13.0环境下项目可正常运行，升级到Node 20.9.0后首页可加载但样式失效
• 精简代码后出现新错误日志：

[3:40:18 PM]  ERROR  [hardsource:b05122e8] Could not freeze ./.nuxt/components/plugin.js: Cannot read properties of undefined (reading 'hash')

[3:40:18 PM]  ERROR  [hardsource:b05122e8] Could not freeze ./.nuxt/router.js: Cannot read properties of undefined (reading 'hash')

• package.json未指定TypeScript版本，因@nuxt/typescript-build存在版本冲突，固定版本会导致项目无法运行

一、解决TS2304 "Cannot find name 'this'" 错误 #

1. 调整类型声明方式
   避免在方法参数位置直接引用this.$refs，改用类型别名提前声明：

   // 组件script顶部定义类型
   type ComponentRefs = typeof this.$refs
   
   handleKeyDownEnter(refsItem: keyof ComponentRefs) {
     return () => {
       this.$refs[refsItem]?.handleFocus()
     }
   }
   

   也可以使用keyof InstanceType<typeof YourComponent>（需给组件命名），让TypeScript提前推断this的类型范围。

2. 锁定兼容的TypeScript版本
   Nuxt 2.17.x与TypeScript 4.x系列兼容性更好，通过resolutions强制指定版本，规避冲突：

   // package.json中添加
   "resolutions": {
     "typescript": "~4.9.5"
   }
   

   执行yarn install后重新构建项目。

3. 优化Nuxt TS配置
   在nuxt.config.js中开启严格类型检查，帮助TypeScript更准确推断this类型：

   export default {
     typescript: {
       strict: true,
       typeCheck: true,
       ignoreNotFoundWarnings: false
     }
   }
   

二、解决Hardsource缓存冻结错误 #

1. 直接禁用Hardsource缓存
   Hardsource在Node 18+环境下存在兼容性问题，在nuxt.config.js中关闭：

   export default {
     build: {
       hardSource: false
     }
   }
   

   同时删除.nuxt和node_modules/.cache/hard-source目录，重新执行构建。

2. 升级Hardsource插件版本
   若需保留缓存，升级到兼容Node 18的版本：

   "devDependencies": {
     "hard-source-webpack-plugin": "^0.13.1"
   }
   

   执行yarn install后重新构建。

三、Node 20.x环境下样式失效问题 #

1. 升级PostCSS相关依赖
   Nuxt 2.x默认PostCSS版本与Node 20不兼容，更新依赖：

   "devDependencies": {
     "postcss": "^8.4.38",
     "postcss-loader": "^7.3.3"
   }
   

2. 验证样式加载配置
   在nuxt.config.js中确认样式预处理器配置正确：

   export default {
     css: ['~/assets/css/main.scss'],
     build: {
       postcss: {
         plugins: {
           autoprefixer: {}
         }
       }
     }
   }
   

通用排查步骤 #

1. 彻底清理缓存
   执行以下命令重置依赖与构建缓存：

   rm -rf .nuxt node_modules yarn.lock
   yarn cache clean
   yarn install
   

2. 使用推荐Node版本
   Nuxt 2.17.x官方推荐Node 14.x-18.x，优先用Node 18.x稳定版排查问题，规避Node 20.x的兼容性风险。

内容的提问来源于stack exchange，提问作者Tran Vu Dang Khoa