Bitbucket Pipeline中Docker构建Next.js时next build卡住内存溢出

这类构建卡死、无报错最终内存不足退出的问题在Next.js + CI Docker构建场景非常普遍：本地能正常构建是因为开发机内存普遍在16G以上，资源充足；而Bitbucket Pipelines默认构建实例仅分配4G甚至2G内存，加上Node.js默认不会感知Docker容器的cgroup内存限制，会按宿主机总内存申请堆空间，很容易在生产构建的代码压缩、静态预渲染、依赖打包环节把容器内存打满，被系统OOM杀手直接终止进程——进程被强杀时往往来不及输出错误日志，就表现为卡在「Creating an optimized production build」阶段无响应，最终超时/退出。

• 先在Dockerfile的builder阶段，yarn build命令前添加环境变量ENV NODE_OPTIONS="--trace-gc"，重新跑构建，如果日志最后出现JavaScript heap out of memory字样，可直接确认是Node堆内存不足；如果没有任何Node层报错直接退出，就是容器内存被打满触发系统级OOM。
• 本地复现验证：把本地Docker的运行内存限制到2G/4G，再执行和CI完全一致的构建命令，如果出现和CI一样的卡死问题，就能排除代码、依赖配置错误，确认是内存配额问题。

按生效成本从低到高排序：

1. 调整Node构建内存参数（最快修复） #

在Dockerfile的builder阶段，执行yarn build前添加内存上限配置，让Node主动适配容器内存配额，避免无节制申请内存：

# 放在builder阶段的RUN yarn build之前即可
ENV NODE_OPTIONS="--max-old-space-size=3072"

如果用Bitbucket默认4G内存的构建实例，给Node堆分配3G，剩余1G留给系统、Webpack子进程使用，基本不会触发容器级OOM。

2. 调整Next.js构建配置降低内存消耗 #

修改next.config.js，关闭高内存消耗的非必要构建逻辑：

/** @type {import('next').NextConfig} */
const nextConfig = {
  output: 'standalone',
  // 关闭生产环境浏览器端sourcemap生成，可降低30%左右构建内存占用
  productionBrowserSourceMaps: false,
  // 开启SWC压缩替代Terser，压缩速度更快、内存占用更低
  swcMinify: true,
  experimental: {
    // 限制构建时的并发线程数，默认值为CPU核心数*2，CI环境核心数高时并发过大会快速吃光内存
    cpus: 2
  }
}

module.exports = nextConfig

3. 提升CI构建实例内存配额 #

如果上述调整后仍然构建失败，直接在bitbucket-pipelines.yml中为构建步骤分配更高规格的实例：

pipelines:
  default:
    - step:
        name: Build Next.js app
        # 分配8G内存的构建实例，可覆盖绝大多数中大型Next.js项目的构建需求
        size: 2x
        script:
          - docker build . -t next-production-image

4. 优化Docker构建上下文 #

在项目根目录添加.dockerignore文件，排除不需要参与构建的文件，减少构建阶段要扫描处理的文件总量，也能降低额外内存开销：

node_modules
.next
.git
*.md
test
__tests__
.env.local
.dockerignore
Dockerfile

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