Nuxt 3项目GitHub Actions执行nuxi prepare失败求助

算力阿峰

2026-7-29

Nuxt 3 GitHub Actions 里 nuxi prepare 执行失败排查

之前Nuxt 2的GitHub Actions配置一直正常，换成Nuxt 3后nuxi prepare就报错，大概率不是Nuxi本身的问题，先从环境配置入手排查：

你提供的Workflow片段

- if: ${{env.USE_CACHE == 'false'}} 
    name: Setup Node (NO-CACHE)
    uses: actions/setup-node@v1
    with:
      node-version: '18'
  - if: ${{env.USE_CACHE == 'false'}}
    name: npm ci (NO-CACHE)
    run: npm ci

从报错截图显示的「nuxi 命令未找到」来看，核心问题是环境未正确安装Nuxi或路径配置异常。

具体解决步骤

升级 actions/setup-node 版本：你当前使用的v1版本过于老旧，对Node.js 18的支持存在缺陷，升级到v4后能解决大部分环境变量和依赖路径问题。修改为：
```
uses: actions/setup-node@v4
```
用npx直接调用本地Nuxi：如果npm ci安装依赖后仍找不到nuxi命令，将nuxi prepare替换为npx nuxi prepare，这样会自动读取node_modules/.bin下的本地Nuxi。
全局安装Nuxi兜底：如果上述方法无效，在Workflow中添加全局安装步骤确保命令可被识别：
```
- run: npm install -g nuxi
```
明确版本差异：Nuxt 3使用nuxi执行准备、构建等操作是正常的版本设计，和Nuxt 2用nuxt命令属于版本差异，无需纠结更换工具。