Next.js 14项目在Digital Ocean构建失败：无法解析@路径模块

问题现象 #

代码在Vercel上能正常运行，但在Digital Ocean执行自定义构建命令npm run build时，出现如下错误：

Module not found: Can't resolve '@/app/component/Hello'

相关代码如下：

组件代码（app/component/Hello.js） #

import React from "react";

const Hello = () => {
  return <h1>Hello, World!</h1>;
};

export default Hello;

页面代码（app/page.tsx） #

import Image from "next/image";
import styles from "./page.module.css";
import Hello from "@/app/component/Hello";

export default function Home() {
  return (
    <div className={styles.page}>
      <main className={styles.main}>
        <Hello />
      </main>
    </div>
  );
}

解决方案 #

• 配置路径映射文件
  在项目根目录创建或修改jsconfig.json（JavaScript项目）或tsconfig.json（TypeScript项目），添加baseUrl和paths配置，确保@能正确映射到项目根目录：

  {
    "compilerOptions": {
      "baseUrl": ".",
      "paths": {
        "@/*": ["./*"]
      }
    }
  }
  

  该配置会将@/app/component/Hello解析为项目根目录下的app/component/Hello.js。

• 确认配置文件已提交至版本库
  确保jsconfig.json或tsconfig.json未被.gitignore排除，且已推送到代码仓库，避免Digital Ocean构建环境无法读取配置。

• 锁定Next.js版本并同步依赖
  检查package.json中的Next.js版本，确保Digital Ocean构建环境安装的版本与Vercel一致。可在package.json中明确指定版本（如"next": "14.0.4"），然后修改构建命令为：

  npm ci && npm run build
  

  npm ci会严格按照package-lock.json安装依赖，避免版本不一致问题。

• 清理构建缓存
  若之前的构建缓存导致异常，可在构建命令前添加缓存清理步骤：

  rm -rf node_modules .next && npm install && npm run build
  

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