使用Docker Compose运行Next.js应用时，容器内node_modules存在却提示next命令未找到

报错根因 #

你遇到的next: not found（退出码127）报错，根源是Docker Compose的 bind mount 配置遮蔽了容器构建阶段生成的有效node_modules目录：

• 镜像构建过程是在完全隔离的镜像分层中运行的，这一阶段执行yarn install会正常在容器的/frontend-app/node_modules路径下装好全部依赖（包括Next.js的可执行文件），所以docker-compose build的日志完全正常，没有报错。
• 执行docker-compose up启动容器时，配置的第一行bind mount规则./frontend/next:/frontend-app，会把你本地主机上的./frontend/next目录内容完全覆盖挂载到容器的/frontend-app路径下：
  • 你本地的项目目录因为从未在主机侧安装过Node依赖，加上.dockerignore排除了node_modules，本身要么没有node_modules目录，要么存在一个空的node_modules文件夹
  • 这时候来自主机的、没有实际依赖内容的目录结构，会把镜像层里已经装好完整依赖的/frontend-app/node_modules完全遮挡。你在容器内执行ls /frontend-app能看到node_modules目录存在，本质要么是本地空目录被直接挂载进去，要么是Docker挂载时自动创建了对应的空目录，目录本身存在但没有可执行文件
• 容器启动后执行yarn dev时，自然找不到next可执行文件，最终触发命令不存在的报错。

配置修复方案 #

• 删除两行冗余的单独文件挂载规则：./frontend/next/package.json:/frontend-app/package.json、./frontend/next/yarn.lock:/frontend-app/yarn.lock。整目录的bind mount已经会自动把这两个文件同步到容器内，不需要重复单独挂载。
• 在volumes配置中新增一个匿名卷，单独保留容器内的node_modules目录，避免被主机的bind mount覆盖。

修复后的对应配置片段：

volumes:
  - ./frontend/next:/frontend-app
  - /frontend-app/node_modules

这个匿名卷的作用是：Docker会优先把镜像构建阶段生成的/frontend-app/node_modules内容同步到独立卷中，bind mount挂载主机目录时会跳过该路径的覆盖逻辑，既保证代码目录的热重载效果，又让容器始终能正常访问构建时装好的依赖。

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