拉取仓库代码启动Nuxt报FATAL Nuxt instance is unavailable错误

从错误堆栈可以直接定位，报错是nuxt-webpack-optimisations模块在初始化阶段调用defineNuxtModule时，Nuxt核心实例尚未完成挂载导致的。之前运行无报错、拉取新代码重装依赖后触发，本质是依赖版本兼容性冲突，不存在代码业务逻辑问题。

按出现概率从高到低排查：

• 第一优先级看nuxt-webpack-optimisations依赖：这个包是Nuxt3早期生态的第三方优化模块，早已停止维护，Nuxt 3.4及以上版本内置了绝大多数webpack构建优化能力，和高版本Nuxt完全不兼容，只要项目升级了Nuxt版本，这个包大概率会触发实例不存在的报错
• 第二优先级核对核心依赖版本一致性：Nuxt生态要求nuxt、@nuxt/kit、@nuxt/core三个核心包的版本必须完全对齐，npm install如果没有锁文件约束，很容易出现子依赖自动升级、版本混装的问题，直接导致实例初始化时序错乱
• 第三优先级核对本地Node版本：新拉的代码如果调整了Node版本要求（比如从16升到18），旧版本Node跑ESM模块加载时会出现时序问题，触发同类报错
• 第四优先级核对锁文件：如果拉代码时没有拉取仓库提交的锁文件，本地自动生成的锁文件会拉取符合版本范围的最新依赖，很容易引入不兼容的更新

1. 优先移除废弃依赖（推荐，解决90%以上同类场景）
   直接执行命令卸载停止维护的包：
   npm uninstall nuxt-webpack-optimisations
   随后打开项目根目录的nuxt.config.js/nuxt.config.ts，找到modules配置数组，删除其中nuxt-webpack-optimisations的引用项，保存后直接执行npm run dev即可正常启动，不需要额外补其他优化配置，高版本Nuxt的默认构建优化已经覆盖这个包的所有能力。

2. 强制对齐核心依赖版本（特殊场景必须保留该包时使用）
   先彻底清理旧依赖和锁文件：

   # Windows命令行执行
   rd /s /q node_modules
   del package-lock.json
   
   # macOS/Linux命令行执行
   rm -rf node_modules package-lock.json
   

   打开package.json，添加resolutions配置强制所有子依赖里的@nuxt/kit版本和你项目安装的nuxt版本完全一致，示例：

   {
     "dependencies": {
       "nuxt": "3.6.5"
     },
     "resolutions": {
       "@nuxt/kit": "3.6.5"
     }
   }
   

   保存后重新执行npm install，安装完成后再启动项目。

3. 对齐Node版本
   查看项目根目录.nvmrc或者package.json里engines字段标注的Node版本要求，用nvm切换到对应版本后，重新执行依赖安装和启动命令即可。

4. 恢复仓库锁文件
   如果本地锁文件是自己生成的，直接删除本地锁文件，拉取代码仓库里提交的官方锁文件（package-lock.json/yarn.lock/pnpm-lock.yaml），再重新执行依赖安装，避免依赖自动升级引入的不兼容问题。

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