docker-compose构建Next.js项目时报Cannot find module './src'错误

安全阿岳

2026-11-5

问题背景

操作流程：近期依次执行npm install与npm update命令后，尝试构建Docker容器，构建过程中持续返回完全一致的堆栈报错。
核心构建报错日志：

Step 7/8 : RUN npm run build
 ---> Running in 9d7f766e2cf7

> docs.rpg.riotgames.io@1.0.0 build /riot/rpg-docs-hub
> next build

(node:18) ExperimentalWarning: The fs.promises API is experimental
Loaded env from /riot/rpg-docs-hub/.env

> Build error occurred
{ Error: Cannot find module './src'
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:581:15)
    at Function.Module._load (internal/modules/cjs/loader.js:507:25)
    at Module.require (internal/modules/cjs/loader.js:637:17)
    at require (internal/modules/cjs/helpers.js:20:18)
    at Object.<anonymous> (/riot/rpg-docs-hub/node_modules/dotenv-webpack/index.js:9:14)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32)
    at tryModuleLoad (internal/modules/cjs/loader.js:538:12)
    at Function.Module._load (internal/modules/cjs/loader.js:530:3)
    at Module.require (internal/modules/cjs/loader.js:637:17)
    at require (internal/modules/cjs/helpers.js:20:18)
    at Object.<anonymous> (/riot/rpg-docs-hub/next.config.js:4:16)
    at Module._compile (internal/modules/cjs/loader.js:689:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:700:10)
    at Module.load (internal/modules/cjs/loader.js:599:32) code: 'MODULE_NOT_FOUND' }
npm ERR! code ELIFECYCLE
npm ERR! errno 1
npm ERR! docs.rpg.riotgames.io@1.0.0 build: `next build`
npm ERR! Exit status 1
npm ERR! 
npm ERR! Failed at the docs.rpg.riotgames.io@1.0.0 build script.
npm ERR! This is probably not a problem with npm. There is likely additional logging output above.

npm ERR! A complete log of this run can be found in:
npm ERR!     /root/.npm/_logs/2021-02-03T19_16_10_771Z-debug.log
ERROR: Service 'rpg-docs-hub' failed to build : The command '/bin/sh -c npm run build' returned a non-zero code: 1

已尝试的排查操作：
- 多轮重复执行npm install与npm update命令
- 执行docker-compose up --build命令全量重新构建容器
- 针对webpack生态关联的报错，执行npm install --save-dev dotenv-webpack命令单独安装依赖
以上操作执行后，报错内容无任何变化。

根因说明

从报错栈可以定位，缺失的./src模块路径来自dotenv-webpack包的入口文件。出现该问题的核心逻辑是：全量执行npm update时，dotenv-webpack被自动升级到了版本结构不兼容的新版本，叠加Docker构建层缓存、本地npm缓存的干扰，导致包安装不完整——新版本的入口文件index.js已经覆盖了旧版本的文件，但对应的src模块目录没有被完整写入node_modules，最终触发模块找不到的报错。
之前单独执行安装dotenv-webpack没有生效，是因为没有清理旧缓存，且安装时没有锁定与项目兼容的版本，依然会拉取到结构不匹配的包文件。

解决步骤

第一步：清理全量缓存，避免旧文件干扰
- 本地删除项目目录下的node_modules文件夹与package-lock.json文件
- 执行docker system prune -a命令清理所有无效的Docker镜像、构建缓存
第二步：锁定兼容版本
- 在项目的package.json中，为dotenv-webpack指定与当前Next.js版本兼容的固定版本号（优先选择项目最初使用的历史版本，避免使用最新的结构调整版本）
第三步：重新安装依赖
- 在项目目录下执行npm install，安装完成后手动检查node_modules/dotenv-webpack目录结构，确认index.js中require的相对路径对应的文件真实存在，避免出现安装不全的问题
第四步：重新执行Docker容器构建

注意事项

无特殊升级需求时不要执行全量npm update命令：该命令会自动跨小版本升级所有依赖，极易出现模块结构不兼容、配置失效的问题
编写Dockerfile时，不要直接将本地宿主机的node_modules目录拷贝进镜像，要在镜像内部通过RUN npm install的步骤生成依赖目录，避免宿主机的环境差异、缓存文件导致的依赖异常

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