Mac 本地开发：用 Nginx 配置自定义域名代理到本地服务

前言

在日常开发中，我们经常需要在本地模拟线上环境，比如让一个自定义域名指向本地正在运行的服务。这在联调、测试 Cookie 跨域、模拟网关转发等场景下非常实用。

本文记录如何在 Mac 上通过 Nginx 将一个自定义域名（如 pre-api.myapp.local）代理到本地的 8080 端口服务。

环境准备

macOS（本文使用 Apple Silicon，Homebrew 安装路径为 /opt/homebrew）
Nginx（通过 Homebrew 安装）

bash 复制代码

brew install nginx

安装完成后，Nginx 的配置目录位于：

bash 复制代码

/opt/homebrew/etc/nginx/

步骤一：配置 hosts 解析

将自定义域名指向本地 127.0.0.1，编辑 /etc/hosts 文件：

bash 复制代码

sudo vim /etc/hosts

添加一行：

lua 复制代码

127.0.0.1  pre-api.myapp.local

保存后，本机访问 pre-api.myapp.local 就会解析到 127.0.0.1。

步骤二：配置 Nginx upstream

编辑或创建 upstream 配置文件，定义后端服务地址：

bash 复制代码

vim /opt/homebrew/etc/nginx/upstream-local.conf

添加内容：

nginx 复制代码

upstream pre-api.myapp.local {
    server 127.0.0.1:8080 weight=1 max_fails=1 fail_timeout=10s;
}

这里将 pre-api.myapp.local 这个 upstream 指向本地 8080 端口。

步骤三：配置 server block

创建域名对应的 server 配置文件：

bash 复制代码

vim /opt/homebrew/etc/nginx/domains/pre-api.myapp.local

写入以下内容：

nginx 复制代码

server
{
  listen                  80;
  server_name             pre-api.myapp.local;

  access_log              /tmp/nginx/logs/pre-api.myapp.local/access.log;
  error_log               /tmp/nginx/logs/pre-api.myapp.local/error.log warn;

  location /
  {
    proxy_next_upstream     http_500 http_502 http_503 http_504 error timeout invalid_header;
    proxy_set_header        Host  $host;
    proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_pass              http://pre-api.myapp.local;
    proxy_buffer_size       128k;
    proxy_buffers           4 256k;
    proxy_busy_buffers_size 256k;
    expires                 1d;
  }
}

关键配置说明：

配置项	作用
`listen 80`	监听 80 端口
`server_name`	匹配请求的域名
`proxy_set_header Host $host`	透传原始 Host 头，后端可获取真实域名
`proxy_set_header X-Forwarded-For`	透传客户端真实 IP
`proxy_pass`	转发到对应的 upstream

步骤四：在 nginx.conf 中引入配置

确保主配置文件中包含了 upstream 和 domains 目录：

bash 复制代码

vim /opt/homebrew/etc/nginx/nginx.conf

在 http {} 块中确认有以下 include：

nginx 复制代码

http {
    # ... 其他配置 ...
    include upstream-local.conf;
    include domains/pre-api.myapp.local;
}

步骤五：创建日志目录并启动

bash 复制代码

# 创建日志目录
mkdir -p /tmp/nginx/logs/pre-api.myapp.local

# 检测配置是否正确
nginx -t

# 启动 nginx
nginx

# 如果 nginx 已在运行，重启即可
nginx -s stop && nginx

验证

确保本地 8080 端口的服务已启动，然后在浏览器或终端访问：

bash 复制代码

curl http://pre-api.myapp.local/

如果返回了你本地 8080 服务的响应，说明配置成功。

常用 Nginx 命令

bash 复制代码

nginx              # 启动
nginx -s stop      # 立即停止
nginx -s quit      # 优雅停止（等待请求处理完）
nginx -s reload    # 重新加载配置（不中断服务）
nginx -t           # 测试配置文件语法

常见问题

1. 启动报错：日志目录不存在

css 复制代码

nginx: [emerg] open() "/path/to/access.log" failed (2: No such file or directory)

解决： 手动创建日志目录 mkdir -p /path/to/log/dir

2. 启动报错：Permission denied

css 复制代码

nginx: [emerg] open() "/path/to/access.log" failed (13: Permission denied)

解决： 给日志目录赋予写权限 chmod 777 /path/to/log/dir

3. 域名访问不到本地服务

排查顺序：

检查 hosts 解析： ping pre-api.myapp.local 是否指向 127.0.0.1
检查 server_name： 配置文件中的 server_name 是否与域名一致
检查 upstream： proxy_pass 中引用的 upstream 名称是否匹配
检查本地服务： curl http://127.0.0.1:8080 是否有响应

4. 警告：conflicting server name

vbnet 复制代码

nginx: [warn] conflicting server name "xxx" on 0.0.0.0:80, ignored

原因： 同一个 server_name 在多个配置文件中重复定义，检查 domains/ 目录下是否有重复。

总结

整个流程只需要四步：

hosts 文件添加域名解析
配置 upstream 指向本地端口
配置 server block 匹配域名并转发
重启 nginx