自托管GitLab CI部署Nuxt 3 SSR至Vercel失败求助

核心问题分析 #

GitLab CI的干净环境中，Vercel CLI默认未正确识别Nuxt3的SSR构建产物路径（默认是.output而非静态站点的dist），而本地环境因存在Vercel项目配置缓存或本地预设，能自动适配。

具体解决步骤 #

1. 添加Vercel配置文件指定输出路径 #

在项目根目录创建vercel.json，明确告知Vercel正确的构建和输出配置：

{
  "buildCommand": "nuxt build",
  "devCommand": "nuxt dev",
  "installCommand": "npm install",
  "outputDirectory": ".output"
}

2. 调整GitLab CI部署脚本 #

避免全局安装vercel引发版本不一致问题，改用项目本地依赖执行：

script:
  - npm install
  - npx vercel pull --yes --environment=preview --token=$VERCEL_TOKEN
  - npx vercel build --token=$VERCEL_TOKEN
  - npx vercel deploy --prebuilt --token=$VERCEL_TOKEN

需提前在项目package.json的devDependencies中添加vercel依赖。

3. 清理GitLab CI缓存 #

GitLab CI的缓存可能残留旧的Vercel配置，导致路径识别错误。可在.gitlab-ci.yml中添加缓存清理逻辑，或手动进入GitLab项目的CI/CD设置页面清除缓存。

4. 确认Vercel项目框架预设 #

在Vercel项目的设置界面，将Framework Preset设置为Nuxt.js，让Vercel自动适配Nuxt3的SSR构建逻辑。

5. 校验CI环境变量 #

确保GitLab CI中配置的VERCEL_TOKEN权限正确，且变量已设为masked类型保护敏感信息。

本地成功的原因 #

本地环境中，Vercel CLI通过之前的部署操作或本地初始化，已自动识别Nuxt3框架类型和输出路径；而GitLab CI是全新的隔离环境，缺少这些预设配置，需要手动指定。

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