Next.js使用Docker搭建开发环境访问报错如何排查修复

1. 调整Next.js开发服务监听地址 #

Next.js 开发模式默认仅监听容器内部的127.0.0.1地址，宿主机无法直接访问容器服务，需要修改启动命令指定监听所有网卡：
修改Dockerfile中的CMD配置：

CMD ["yarn", "dev", "--hostname", "0.0.0.0"]

你也可以选择在项目的next.config.js中配置全局监听规则，效果一致。

2. 升级Node.js基础镜像版本 #

你当前使用的node:12-alpine版本过低，Next.js 11及以上版本已停止对Node.js 12的支持，会出现依赖兼容性报错、运行时异常问题。建议根据你的Next.js版本匹配Node.js LTS版本，至少使用16及以上版本，示例：

FROM node:18-alpine

3. 清理.next目录缓存 #

你在docker-compose.yaml中配置了.next目录的匿名卷，容器重启时会复用旧的构建缓存，容易出现产物与当前代码不匹配的问题。先执行命令停止容器并清理关联卷：

docker-compose down -v

如果不需要持久化构建缓存，也可以直接删除docker-compose.yaml中- /usr/src/app/.next这行配置。

4. 校验本地挂载目录正确性 #

确认本地./web目录下包含完整的Next.js项目核心文件，如pages/app目录、next.config.js、package.json等，避免挂载路径错误导致容器内项目文件缺失。

5. 重新构建启动服务 #

执行以下命令重新构建镜像并启动容器：

docker-compose up --build

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