Next.js MDX文件本地正常但AWS Docker环境无法加载问题

Next.js项目中的MDX文件在本地环境可正常加载，但部署到AWS Docker流水线后无法被Next.js收集（页面不生成、内容无法加载）。相关配置信息如下：

依赖版本 #

"@next/mdx": "^14.0.4",
"next": "13.5.6"

Dockerfile配置 #

FROM --platform=linux/amd64 node:20-bullseye

WORKDIR /app

COPY tsconfig.json .
COPY package.json .
COPY package-lock.json .
COPY postcss.config.js .

COPY public public/
COPY src src/

RUN npm install

ENV NODE_ENV production

RUN npm run build

EXPOSE 3000

ENV PORT 3000
ENV HOSTNAME "0.0.0.0"

CMD ["npm", "run", "start"]

next.config.js配置 #

/** @type {import('next').NextConfig} */
const withMDX = require('@next/mdx')()

const nextConfig = {
  experimental: {
    instrumentationHook: process.env.NODE_ENV === 'production' ? true : false,
  },
  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
}

module.exports = withMDX(nextConfig);

此前有相关Next.js官方Issue标注“有时可用”但未解决，该问题在AWS Docker环境中持续复现，不清楚本地与AWS环境的配置差异，寻求解决方案。

1. 统一依赖版本，修复跨版本兼容问题 #

@next/mdx版本（14.0.4）高于Next.js核心版本（13.5.6），易引发构建兼容性问题。将@next/mdx降级到与核心版本匹配：

"@next/mdx": "^13.5.6",
"next": "13.5.6"

修改后重新执行npm install，Docker构建时保持package-lock.json的复制，确保依赖完全一致。

2. 确认Docker构建上下文包含所有MDX文件 #

• 若MDX文件存放在src/app或src/pages目录，当前COPY src src/已覆盖，但要检查.dockerignore或.gitignore是否误排除了.mdx后缀文件；
• 若MDX文件在其他目录（如content/），需在Dockerfile中添加对应复制指令：

COPY content content/

3. 显式配置MDX加载器选项 #

在next.config.js中明确MDX的加载规则，避免环境差异导致自动配置失效：

const withMDX = require('@next/mdx')({
  extension: /\.mdx?$/,
  options: {
    remarkPlugins: [],
    rehypePlugins: [],
  },
})

const nextConfig = {
  experimental: {
    instrumentationHook: process.env.NODE_ENV === 'production' ? true : false,
  },
  pageExtensions: ['js', 'jsx', 'mdx', 'ts', 'tsx'],
}

module.exports = withMDX(nextConfig);

4. 调整Docker构建的环境变量顺序 #

当前Dockerfile先执行npm install再设置NODE_ENV=production，会导致安装devDependencies，可能引发缓存或构建异常。调整顺序并使用npm ci确保依赖一致性：

FROM --platform=linux/amd64 node:20-bullseye

WORKDIR /app

COPY tsconfig.json .
COPY package.json .
COPY package-lock.json .
COPY postcss.config.js .

COPY public public/
COPY src src/

ENV NODE_ENV production

RUN npm ci --only=production

RUN npm run build

EXPOSE 3000

ENV PORT 3000
ENV HOSTNAME "0.0.0.0"

CMD ["npm", "run", "start"]

5. 清理AWS流水线的构建缓存 #

若AWS流水线启用了构建缓存，可能残留旧产物导致MDX未被重新处理。在构建步骤中添加清理命令：

RUN rm -rf .next/ && rm -rf node_modules/

将该命令放在npm install前，确保构建环境完全干净。

1. 本地模拟Docker构建：执行docker build -t next-mdx-test .，运行容器后检查MDX内容是否正常加载；
2. 查看AWS流水线的构建日志，排查是否存在MDX相关的警告或错误（如Module not found、Page not generated）。

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