部署Next.js到GitHub Pages时遇@splinetool/runtime解析失败求助

问题分析 #

本地执行npm run build正常，但GitHub Actions中报错找不到@splinetool/runtime，核心原因是：

• 本地环境可能通过npm的自动peer依赖安装机制，间接安装了该依赖，但package-lock.json中未明确记录
• GitHub Actions使用npm ci命令，会严格按照package-lock.json安装依赖，不会自动补充缺失的peer依赖

具体解决步骤 #

1. 显式安装缺失的依赖 #

在本地项目中执行以下命令，将@splinetool/runtime添加为项目依赖：

npm install @splinetool/runtime

执行完成后，提交更新后的package.json和package-lock.json到GitHub仓库，重新触发CI构建。

2. 调整GitHub Actions工作流（可选，若第一步无效） #

如果第一步无法解决，可尝试将工作流中的npm ci替换为npm install，让npm自动处理依赖：

# 替换原步骤中的npm ci
- run: npm install

注意：npm install会更新package-lock.json，若团队协作需确保版本一致性，建议优先使用第一种方案。

3. 客户端动态导入Spline组件（针对SSR场景优化） #

如果你的Spline组件仅在客户端渲染，可在Next.js中使用动态导入并禁用SSR，避免构建时在服务端尝试解析该依赖：

// 在WelcomeComp.tsx中修改导入方式
import dynamic from 'next/dynamic';

const Spline = dynamic(() => import('@splinetool/react-spline'), {
  ssr: false,
});

验证方案 #

提交修改后，触发GitHub Actions构建，若报错消失且成功生成out文件夹并部署，则问题解决。

内容的提问来源于stack exchange，提问作者Abdallah Abu sedo