如何解决Next.js静态应用Dockerfile构建时的tailwindcss模块找不到错误？

问题场景 #

在Windows 11 Home + Docker Desktop（通过WSL/Ubuntu发起构建）环境下，构建Next.js静态应用生产Docker镜像时，执行以下命令后构建失败：

# 清理相关镜像以重新构建
docker rmi -f $(docker images -a -q)

# 构建并运行
docker-compose -f docker-compose.prod.yaml up --build

错误信息 #

构建过程中触发如下错误：

=> ERROR [ui builder 6/6] RUN npm run build                                                     3.0s
------
 > [ui builder 6/6] RUN npm run build:
0.458 
0.458 > ui@0.1.0 build
0.458 > next build
0.458 
0.803 Attention: Next.js now collects completely anonymous telemetry regarding usage.
0.803 This information is used to shape Next.js' roadmap and prioritize features.
0.803 You can learn more, including how to opt-out if you'd not like to participate in this anonymous program, by visiting the following URL:
0.803 https://nextjs.org/telemetry
0.803 
0.841   ▲ Next.js 14.2.4
0.841 
0.872    Creating an optimized production build ...
2.913 Failed to compile.
2.913 
2.913 src/app/layout.tsx
2.913 An error occurred in `next/font`.
2.913 
2.913 Error: Cannot find module 'tailwindcss'
2.913 Require stack:
2.913 - /home/node/app/node_modules/next/dist/build/webpack/config/blocks/css/plugins.js
2.913 - /home/node/app/node_modules/next/dist/build/webpack/config/blocks/css/index.js
2.913 - /home/node/app/node_modules/next/dist/build/webpack/config/index.js
2.913 - /home/node/app/node_modules/next/dist/build/webpack-config.js
2.913 - /home/node/app/node_modules/next/dist/build/webpack/plugins/next-trace-entrypoints-plugin.js
2.913 - /home/node/app/node_modules/next/dist/build/collect-build-traces.js
2.913 - /home/node/app/node_modules/next/dist/build/index.js
2.913 - /home/node/app/node_modules/next/dist/cli/next-build.js
2.913     at Module._resolveFilename (node:internal/modules/cjs/loader:1090:15)
2.913     at /home/node/app/node_modules/next/dist/server/require-hook.js:55:36
2.913     at Function.resolve (node:internal/modules/helpers:125:19)
2.913     at loadPlugin (/home/node/app/node_modules/next/dist/build/webpack/config/blocks/css/plugins.js:49:32)
2.913     at /home/node/app/node_modules/next/dist/build/webpack/config/blocks/css/plugins.js:157:56
2.913     at Array.map (<anonymous>)
2.913     at getPostCssPlugins (/home/node/app/node_modules/next/dist/build/webpack/config/blocks/css/plugins.js:157:47)
2.913     at async /home/node/app/node_modules/next/dist/build/webpack/config/blocks/css/index.js:124:36
2.913     at async /home/node/app/node_modules/next/dist/build/webpack/loaders/next-font-loader/index.js:86:33
2.913     at async Span.traceAsyncFn (/home/node/app/node_modules/next/dist/trace/trace.js:154:20)
2.913 
2.914 
2.914 > Build failed because of webpack errors
------
failed to solve: process "/bin/sh -c npm run build" did not complete successfully: exit code: 1

相关配置文件 #

/ui/Dockerfile.prod #

# Build app
FROM node:19 AS builder

# Set working directory
WORKDIR /home/node/app

# Copy package.json and package-lock.json and install dependencies
COPY package.json package-lock.json* ./
RUN npm ci

# Copy the rest of the application files
COPY . .

# Build the Next.js app
RUN npm run build

# Prod image
FROM node:19 AS runner

# Set working directory
WORKDIR /home/node/app

# Copy built files from builder stage
COPY --from=builder /home/node/app/.next ./.next
COPY --from=builder /home/node/app/public ./public
COPY --from=builder /home/node/app/node_modules ./node_modules
COPY --from=builder /home/node/app/package.json ./package.json

# Set environment variables
ENV NODE_ENV=production
ENV PORT=3000

# Expose the port
EXPOSE 3000

# Start the Next.js app
CMD ["npm", "start"]

docker-compose.prod.yaml #

version: '3.8'

services:
    postgres:
        container_name: postgres-prod
        image: postgres:16
        ports:
            - '5432:5432'
        volumes:
            - ./postgresdata:/var/lib/postgresql/data
            - ./src/migrations/dbinit.sql:/docker-entrypoint-initdb.d/dbinit.sql
        restart: always
        environment:
            POSTGRES_USER: ${POSTGRES_USER}
            POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
            POSTGRES_DB: ${POSTGRES_DB}
        networks:
            - app-network

    api:
        container_name: api-prod
        image: 'node:19'
        build:
            context: ./server
            dockerfile: Dockerfile.prod
        user: 'node'
        working_dir: /home/node/app
        environment:
            - 'NODE_ENV=${NODE_ENV}'
            - 'PORT=3000'
            - 'DATABASE_URL=${DATABASE_URL}'
        expose:
            - '3000'
        ports:
            - '3000:3000'
        command: 'npm run dev:migrate:start'
        networks:
            - app-network
        depends_on:
            - postgres

    ui:
        container_name: ui-prod
        build:
            context: ./ui
            dockerfile: Dockerfile.prod
        user: 'node'
        working_dir: /home/node/app
        environment:
            - 'NODE_ENV=production'
            - 'NEXT_PUBLIC_API_URL=${NEXT_PUBLIC_API_URL}'
            - 'NEXT_PUBLIC_SOCKET_URL=${NEXT_PUBLIC_SOCKET_URL}'
        ports:
            - '8080:8080'
        command: 'npm start'
        networks:
            - app-network
        depends_on:
            - api

    nginx:
        build:
            context: ./nginx
            dockerfile: Dockerfile.prod
        container_name: nginx-prod
        restart: always
        tty: true
        ports:
            - '80:80'
        networks:
            - app-network
        depends_on:
            - api
            - ui

networks:
    app-network:
        driver: bridge

/ui/package.json #

{
  "name": "ui",
  "version": "0.1.0",
  "private": true,
  "scripts": {
    "dev": "next dev -p 8080",
    "build": "next build",
    "start": "next start -p 8080",
    "lint": "next lint"
  },
  "dependencies": {
    "@auth0/auth0-react": "^2.2.4",
    "next": "14.2.4",
    "react": "^18",
    "react-dom": "^18",
    "socket.io-client": "^4.7.5"
  },
  "devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "eslint": "^8",
    "eslint-config-next": "14.2.4",
    "next-image-export-optimizer": "^1.14.1",
    "postcss": "^8",
    "tailwindcss": "^3.4.1",
    "typescript": "^5"
  }
}

解决方案 #

问题核心是：npm ci默认仅安装dependencies中的包，但tailwindcss属于devDependencies，而Next.js生产构建阶段需要用到Tailwind处理CSS，导致构建时找不到该模块。

提供两种可行方案：

方案1：安装依赖时包含dev依赖 #

修改Dockerfile.prod中的依赖安装命令，添加--include=dev参数：

# 原命令
# RUN npm ci

# 修改后
RUN npm ci --include=dev

如果需要缩小最终镜像体积，可以在构建完成后清理dev依赖：

# Copy package.json and package-lock.json and install dependencies
COPY package.json package-lock.json* ./
RUN npm ci --include=dev

# Copy the rest of the application files
COPY . .

# Build the Next.js app
RUN npm run build

# 清理dev依赖
RUN npm ci --omit=dev

方案2：将Tailwind相关依赖移至dependencies #

修改package.json，把tailwindcss和postcss从devDependencies移到dependencies中：

"dependencies": {
    "@auth0/auth0-react": "^2.2.4",
    "next": "14.2.4",
    "react": "^18",
    "react-dom": "^18",
    "socket.io-client": "^4.7.5",
    "postcss": "^8",
    "tailwindcss": "^3.4.1"
},
"devDependencies": {
    "@types/node": "^20",
    "@types/react": "^18",
    "@types/react-dom": "^18",
    "eslint": "^8",
    "eslint-config-next": "14.2.4",
    "next-image-export-optimizer": "^1.14.1",
    "typescript": "^5"
}

两种方案任选其一即可，推荐方案1，既能满足构建需求，又能避免运行阶段携带不必要的dev依赖。

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