Next.js Docker部署时静态资源路径错误

Question

在使用Docker部署Next.js应用时，常遇到静态资源路径错误的问题。表现为CSS、JS或图片资源返回404，导致页面样式丢失或功能失效。常见原因包括：未正确配置`next.config.js`中的`assetPrefix`，未使用`next export`导出静态资源，或Docker容器中Nginx等反向代理配置不当，未正确映射`/static`路径。此外，构建时环境变量未生效，也可能导致资源路径错误。解决方法包括检查并设置正确的`assetPrefix`、确保Docker镜像中包含`.next/static`资源目录，并正确配置Nginx或Caddy等反向代理规则，确保静态资源路径被正确解析。

Answer 1

使用Docker部署Next.js应用时静态资源路径错误的深度解析与解决方案

1. 问题现象与初步诊断

在Docker环境中部署Next.js应用后，访问页面时常出现CSS、JavaScript或图片资源返回404错误，导致页面样式丢失或交互功能失效。这类问题通常表现为浏览器开发者工具中网络面板显示/_next/static/*路径请求失败。

• 前端资源加载失败，但HTML结构正常渲染
• 控制台报错：Failed to load resource: the server responded with a status of 404 (Not Found)
• 构建产物存在于本地，但在容器中无法访问

2. 核心原因分析：从配置到构建流程

静态资源路径错误的根本原因可归结为以下几个层面：

1. next.config.js 配置缺失或错误：未设置 assetPrefix 或其值不符合部署环境（如CDN或子路径）
2. 构建模式选择错误：未使用 next export 导出静态站点，却期望以纯静态方式服务
3. Docker镜像构建遗漏资源目录：Dockerfile未正确复制 .next/static 目录
4. 反向代理配置不当：Nginx/Caddy未正确路由 /_next/ 路径至静态文件服务
5. 环境变量未生效：构建时未传入正确的 NEXT_PUBLIC_ASSET_PREFIX 等变量

3. 解决方案层级递进：由浅入深

层级	检查项	修复方法
Level 1	next.config.js 中 assetPrefix 是否设置	添加 assetPrefix: process.env.ASSET_PREFIX || ''
Level 2	是否执行 next build && next export（如适用）	在 package.json 中定义 "build": "next build && next export"
Level 3	Dockerfile 是否复制 .next 目录	确保有 COPY .next .next 指令
Level 4	Nginx 配置是否代理 /_next/ 路径	添加 location ~ ^/_next/ { expires max; } 规则
Level 5	构建时环境变量是否注入	Docker build-arg 传递 ASSET_PREFIX 值

4. 典型配置示例

// next.config.js
const isProd = process.env.NODE_ENV === 'production';
module.exports = {
  assetPrefix: isProd ? 'https://cdn.example.com' : '',
  trailingSlash: false,
};

# Dockerfile
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
ENV NEXT_PUBLIC_ASSET_PREFIX=/static
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/out /usr/share/nginx/html
COPY --from=builder /app/.next/static /usr/share/nginx/html/_next/static
COPY nginx.conf /etc/nginx/nginx.conf

5. 反向代理配置最佳实践

Nginx 是最常见的静态资源服务层，其配置需精确匹配 Next.js 的输出结构：

server {
    listen 80;
    root /usr/share/nginx/html;

    location / {
        try_files $uri $uri/ /index.html;
    }

    location /_next/static/ {
        alias /usr/share/nginx/html/_next/static/;
        expires 1y;
        add_header Cache-Control "public, immutable";
    }
}

6. 构建与部署流程可视化

graph TD
            A[编写代码] --> B[next.config.js 配置 assetPrefix]
            B --> C[npm run build]
            C --> D{是否导出静态?}
            D -- 是 --> E[next export 生成 out/]
            D -- 否 --> F[保留 .next 目录]
            E --> G[Docker COPY out/ 到 Nginx html]
            F --> H[Docker COPY .next/static 到容器]
            G --> I[Nginx 服务静态资源]
            H --> I
            I --> J[用户访问页面，资源正确加载]

7. 环境变量注入策略

为实现多环境灵活部署，建议通过构建参数注入 assetPrefix：

docker build \
  --build-arg ASSET_PREFIX=https://my-cdn.com \
  -t my-next-app .

并在 Dockerfile 中接收：

ARG ASSET_PREFIX
ENV ASSET_PREFIX=$ASSET_PREFIX

8. 调试技巧与验证手段

• 进入运行中的容器：docker exec -it <container> sh
• 检查目录是否存在：ls /usr/share/nginx/html/_next/static
• 直接访问资源URL：http://localhost/_next/static/chunks/main.js
• 查看Nginx错误日志：docker logs <container>
• 使用 curl 模拟请求并观察响应头中的 Content-Type 和状态码

9. Caddy 替代方案配置

对于偏好声明式配置的团队，Caddy 提供更简洁的语法：

example.com {
    root * /srv/public
    file_server
    handle /_next/static/* {
        strip_prefix /_next
        file_server /static
    }
}

10. 高级场景：CDN 与版本化资源管理

在生产环境中，建议结合 S3 + CloudFront 或类似架构，将 _next/static 同步至对象存储，并通过 CDN 分发。此时 assetPrefix 应指向 CDN 域名，并启用 long-term caching。

可通过 GitHub Actions 或 CI/CD 流水线自动完成资源上传与缓存失效。