如何解决Docker构建Next.js应用时的模块无法解析错误

本地构建Next.js应用完全正常，但用Docker执行npm run build时，反复出现类似Module not found: Can't resolve 'app/lib/send_request'的错误。之前用相同的Dockerfile能正常构建，把项目迁移到App Router目录结构后就出问题了。

解决步骤 #

1. 排查大小写问题 #

Linux环境（Docker容器）是大小写敏感的，而本地Windows/macOS默认不敏感。检查模块引用路径和实际文件的大小写是否完全一致，比如你写的app/lib/send_request，对应的文件是不是app/lib/send_request.ts，有没有写成Send_Request.ts或者App/Lib/...这类不一致的情况。

2. 修正tsconfig配置 #

你的tsconfig里include包含了../tailwind.config.ts，但从Dockerfile的复制逻辑看，所有项目文件都被放到了/next_app目录下，说明tsconfig的路径配置存在层级错误：

• 把../tailwind.config.ts改成tailwind.config.ts（如果tailwind配置文件在src目录内）
• 建议引用模块时使用tsconfig里定义的别名，比如把app/lib/send_request改成@/lib/send_request，避免路径解析混乱
• 确保include范围能覆盖所有项目文件，当前的**/*.ts和**/*.tsx基本能满足，但如果有特殊路径可以补充进去

3. 调整Dockerfile的依赖安装逻辑 #

当前Dockerfile的installer阶段只安装了生产依赖，但Next.js构建过程需要devDependencies（比如TypeScript、ESLint等）。修改installer阶段的依赖安装逻辑：

FROM node:20-alpine AS installer

WORKDIR /next_app

# 复制锁文件和package.json，确保依赖安装的一致性
COPY src/package*.json ./

RUN apk add --update python3 make g++ gcc fftw-dev libc6-compat
RUN apk add --update --repository http://dl-3.alpinelinux.org/alpine/edge/testing vips-dev
RUN rm -rf /var/cache/apk/*

# 安装所有依赖（包括dev依赖，用于构建）
RUN npm install

FROM installer AS builder

WORKDIR /next_app

COPY src/. .

RUN npm run build

FROM node:20-alpine

WORKDIR /next_app

COPY --from=builder /next_app/.next ./.next
COPY --from=builder /next_app/package*.json ./
# 生产阶段只安装生产依赖，减小镜像体积
RUN npm install --production

COPY src/.env .

ENV NODE_ENV production
ENV PORT 3000
ENV NEXT_SHARP_PATH /tmp/node_modules/sharp

EXPOSE 3000

CMD ["npm", "start"]

4. 优化Next.js的webpack路径解析 #

在next.config.js里添加明确的路径别名，帮助webpack正确识别App目录下的模块：

const path = require('path');

const nextConfig = {
    reactStrictMode: true,
    swcMinify: true,
    webpack(config) {
        config.resolve.fallback = {
            ...config.resolve.fallback,
            fs: false,
        };
        config.resolve.alias.canvas = false;
        // 添加路径别名
        config.resolve.alias = {
            ...config.resolve.alias,
            'app/lib': path.resolve(__dirname, 'app/lib'),
            '@/lib': path.resolve(__dirname, 'lib'),
        };
        config.module.rules.push({
            test: /\.node$/,
            use: 'node-loader',
        });

        return config;
    },
    images: {
        remotePatterns: [
            {
                protocol: 'https',
                hostname: 'xxxxxxx',
                port: '',
                pathname: '/assets/**',
            },
        ],
    },
    sentry: {
        hideSourceMaps: true,
    },
};

原始配置文件 #

Dockerfile #

FROM node:20-alpine AS installer

WORKDIR /next_app

COPY src/package.json ./

RUN apk add --update python3 make g++ gcc fftw-dev libc6-compat
RUN apk add --update --repository http://dl-3.alpinelinux.org/alpine/edge/testing vips-dev
RUN rm -rf /var/cache/apk/*

RUN npm install --production

FROM installer AS builder

WORKDIR /next_app

COPY src/. .

RUN npm run build

FROM node:20-alpine

WORKDIR /next_app

COPY --from=builder /next_app/.next ./.next
COPY --from=builder /next_app/node_modules ./node_modules
COPY --from=builder /next_app/package.json ./package.json

COPY src/.env .

ENV NODE_ENV production
ENV PORT 3000
ENV NEXT_SHARP_PATH /tmp/node_modules/sharp

EXPOSE 3000

CMD ["npm", "start"]

tsconfig.json #

{
  "compilerOptions": {
    "target": "es5",
    "lib": [
      "dom",
      "dom.iterable",
      "esnext"
    ],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "forceConsistentCasingInFileNames": true,
    "noEmit": true,
    "esModuleInterop": true,
    "module": "esnext",
    "moduleResolution": "node",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "incremental": true,
    "plugins": [
      {
        "name": "next"
      }
    ],
    "baseUrl": ".",
    "paths": {
      "@/ui/*": [
        "ui/*"
      ],
      "@/lib/*": [
        "lib/*"
      ],
      "@/styles/*": [
        "styles/*"
      ],
      "@/app/*": [
        "app/*"
      ]
    },
  },
  "include": [
    "next-env.d.ts",
    "**/*.ts",
    "**/*.tsx",
    ".next/types/**/*.ts",
    "../tailwind.config.ts"
  ],
  "exclude": [
    "node_modules"
  ]
}

next.config.js #

const nextConfig = {
    reactStrictMode: true,
    swcMinify: true,
    webpack(config) {
        config.resolve.fallback = {
            ...config.resolve.fallback,
            fs: false,
        };
        config.resolve.alias.canvas = false;
        config.module.rules.push({
            test: /\.node$/,
            use: 'node-loader',
        });

        return config;
    },
    images: {
        remotePatterns: [
            {
                protocol: 'https',
                hostname: 'xxxxxxx',
                port: '',
                pathname: '/assets/**',
            },
        ],
    },
    sentry: {
        hideSourceMaps: true,
    },
};

内容的提问来源于stack exchange，提问作者Numan Burak Fidan