17 Dec 2025 4 min read Question Collection

本地调试 Next.js 应用：Nginx 反向代理配置详解

问题描述

在本地调试中，通过修改 hosts 文件将域名指向本地，然后通过 nginx 代理到 dev 模式启动的 Next.js 应用，nginx 配置该怎么写？Next.js 服务地址为 http://127.0.0.1:8900。

解决方案概述

这是一个非常典型的本地开发调试配置。通过修改 Hosts 文件将域名指向本地（127.0.0.1），然后使用 Nginx 作为反向代理，将请求转发给在另一个端口（如 8900）运行的 Next.js 开发服务器。

这样做的好处是可以在本地模拟真实的域名环境，方便测试 Cookie、域名相关的逻辑以及多服务代理。

Nginx 配置文件示例

假设你的本地域名为 dev.example.com，以下是一个完整的 Nginx 配置。

# 新建一个配置文件，例如：/etc/nginx/sites-available/dev.example.com
# 然后将其链接到 sites-enabled 目录

server {
    # 监听 80 端口
    listen 80;
    
    # 你配置在 hosts 文件中的本地域名
    server_name dev.example.com;

    # 设置访问日志和错误日志路径（可选，便于调试）
    access_log /var/log/nginx/dev.example.com.access.log;
    error_log /var/log/nginx/dev.example.com.error.log;

    # 代理配置
    location / {
        # Next.js 开发服务器的地址
        proxy_pass http://127.0.0.1:8900;

        # 传递原始主机头，Next.js 可能需要它来构建正确的 URL
        proxy_set_header Host $host;
        
        # 传递用户真实 IP 地址（如果 Nginx 前还有代理，这很重要）
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # WebSocket 支持（Next.js 开发模式的热重载需要）
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        
        # 缓存 WebSocket 连接
        proxy_cache_bypass $http_upgrade;
    }

    # 如果需要，可以添加其他 location 块来处理静态文件或特定路径
    # location /static/ {
    #     alias /path/to/your/static/files/;
    #     expires 1y;
    #     add_header Cache-Control "public, immutable";
    # }
}

配置步骤详解

1. 创建配置文件

# 在合适的路径创建配置文件，例如：
sudo nano /etc/nginx/sites-available/dev.example.com

将上面的配置内容粘贴进去，并根据你的实际情况修改 server_name 和 proxy_pass。

2. 启用站点

# 创建符号链接到 sites-enabled 目录
sudo ln -s /etc/nginx/sites-available/dev.example.com /etc/nginx/sites-enabled/

3. 检查配置语法

# 这是一个非常重要的步骤，确保配置没有语法错误
sudo nginx -t

如果输出 syntax is ok 和 test is successful，说明配置正确。

4. 重载 Nginx

# 使新配置生效
sudo systemctl reload nginx
# 或者使用
# sudo service nginx reload

必需的本地环境设置

1. 修改 Hosts 文件

在你的电脑上修改 hosts 文件，将域名 dev.example.com 指向本机。

Windows: C:\Windows\System32\drivers\etc\hosts
Linux/macOS: /etc/hosts

添加一行：

127.0.0.1 dev.example.com

2. 启动 Next.js 开发服务器

确保你的 Next.js 应用已经在 http://127.0.0.1:8900 上运行。

# 在你的 Next.js 项目根目录下
npm run dev
# 或者
yarn dev
# 或者，如果需要指定端口和主机
next dev -p 8900 -H 127.0.0.1

测试配置

完成以上步骤后，打开浏览器访问 http://dev.example.com。你应该能看到你的 Next.js 应用，并且热重载（HMR）功能应该正常工作。

关键配置项解释

proxy_pass http://127.0.0.1:8900;: 核心指令，将所有请求转发到 Next.js 服务器。
proxy_set_header Host $host;: 确保 Next.js 接收到原始域名 dev.example.com，而不是 127.0.0.1:8900。这对于某些基于域名的逻辑至关重要。
X-Forwarded-* 头: 告知 Next.js 请求的原始信息，这样 req.url 和 req.protocol 等才会正确。
WebSocket 相关配置: Next.js 开发模式使用 WebSocket 实现热重载，这些配置确保了 WebSocket 连接能够正确建立。

可能遇到的问题及解决方案

1. `502 Bad Gateway`

原因: Nginx 无法连接到 http://127.0.0.1:8900。
解决: 确认 Next.js 开发服务器已启动，并且 IP 和端口正确。检查防火墙设置，确保 127.0.0.1 是可访问的地址（如果这是你本机的另一个IP）。

2. 热重载不工作

原因: WebSocket 代理配置不正确。
解决: 仔细检查并添加上面配置中关于 Upgrade 和 Connection 的头部设置。

3. Nginx 报地址已被占用

原因: 可能有其他服务占用了 80 端口。
解决: 可以修改 Nginx 的 listen 端口，例如 listen 8080;，然后通过 http://dev.example.com:8080 访问。

如果你在配置过程中遇到任何问题，可以查看 Nginx 的错误日志（/var/log/nginx/error.log）来获取更详细的诊断信息。