nginx代理实践（一）多项目本地联调

Nginx 配置实现本地多项目集成开发（统一域名+共享登录态）

你希望解决本地开发中「多项目（不同端口）交互、共享登录状态/缓存、无缝跳转」的问题，通过配置 Nginx 实现统一域名访问多端口项目，模拟线上一致的访问体验。本文梳理 Windows 环境下完整的配置流程，优化配置逻辑并补充关键注意事项，确保本地集成开发高效且贴近线上环境。

一、核心目标与技术方案

1. 核心痛点

本地多项目运行在不同端口（如 3000/3001/3002），跨端口访问存在登录态隔离（Cookie 不共享）、路径跳转混乱问题；
需模拟线上域名访问，保证缓存、登录状态与线上一致。

2. 技术方案

Hosts 映射：将自定义本地域名（如 local.dev.yitong.com）映射到 127.0.0.1；
Nginx 反向代理：通过 Nginx 将统一域名的不同路径转发到对应项目的本地端口，实现「一个域名访问多项目」，同时共享 Cookie/登录态。

二、第一步：配置本地 Hosts（映射自定义域名）

1. 操作步骤（Windows 系统）

打开文件管理器，定位到 Hosts 文件路径：
C:\Windows\System32\drivers\etc\hosts（需管理员权限修改）；
右键选择「以记事本/VS Code（管理员）」打开文件；
在文件末尾添加一行，将自定义域名映射到本地回环地址：
1
2
# 本地集成开发域名映射 127.0.0.1 local.dev.yitong.com
保存文件（若提示权限不足，需确认以管理员身份打开编辑器）。

验证 Hosts 配置

打开 CMD 执行以下命令，若返回 127.0.0.1 则配置成功：

1	`ping local.dev.yitong.com`

三、第二步：Nginx 环境准备与配置优化

1. Nginx 下载与目录说明

下载地址：Nginx 官方下载（推荐稳定版，如 1.24.0）；
解压到非中文路径（避免配置报错），示例路径：E:\Program Files\nginx-1.24.0；
核心目录：
- conf/nginx.conf：主配置文件（核心修改）；
- nginx.exe：启动程序；
- logs/：日志目录（配置报错时查看 error.log）。

2. 优化后的 Nginx 核心配置（nginx.conf）

整理原配置，优化路径匹配逻辑、域名配置、代理参数，补充详细注释，解决跨端口转发和登录态共享问题：

# 用户组（默认nobody，Windows可忽略）
#user  nobody;
worker_processes  1; # 工作进程数，Windows建议设为1

# 错误日志配置（调试时开启）
error_log  logs/error.log  info;
pid        logs/nginx.pid;

events {
    worker_connections  1024; # 最大连接数，满足本地开发即可
}

http {
    include       mime.types; # 引入MIME类型映射
    default_type  application/octet-stream;

    # 开启高效文件传输
    sendfile        on;
    # 长连接超时时间
    keepalive_timeout  65;
    # 开启gzip压缩（优化本地访问速度）
    gzip  on;

    # ===================== SSL证书配置（可选，若需HTTPS访问） =====================
    ssl_certificate      E:\cer\fullchain.cer; # 本地SSL证书路径（需替换为实际路径）
    ssl_certificate_key  E:\cer\_.dev.yitong.com.key; # 证书私钥路径
    ssl_session_timeout  5m; # SSL会话超时
    ssl_ciphers          ECDHE-RSA-AES128-GCM-SHA256:ECDHE:ECDH:AES:HIGH:!NULL:!aNULL:!MD5;
    ssl_protocols        TLSv1 TLSv1.1 TLSv1.2; # 兼容主流浏览器
    ssl_prefer_server_ciphers  on;

    # ===================== 核心：反向代理配置（统一域名转发多项目） =====================
    server {
        listen       80; # HTTP端口
        listen       443 ssl http2; # HTTPS端口（配置证书后启用）
        # 关键：绑定自定义本地域名（与Hosts配置一致）
        server_name  local.dev.yitong.com;
        # 默认首页
        index        index.html index.htm;

        # -------------------- 项目1：pc-account（3002端口） --------------------
        # ^~ 表示优先匹配该路径，避免被根路径覆盖
        location ^~ /vc3/wx/ {
            # 代理到本地3002端口（替换为实际项目端口）
            proxy_pass  http://127.0.0.1:3002/;
            # 关键：传递Host头，保证项目识别域名（解决登录态失效）
            proxy_set_header  Host  $host;
            # 传递客户端IP
            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
            # 禁用缓存（本地开发避免缓存干扰）
            proxy_buffering off;
        }

        # -------------------- 项目2：ytwweb（3001端口） --------------------
        # 匹配/ytwweb相关路径（按实际项目路径调整）
        location ^~ /goods/        { proxy_pass http://127.0.0.1:3001/goods/; }
        location ^~ /courseware/   { proxy_pass http://127.0.0.1:3001/courseware/; }
        location ^~ /aboutus/      { proxy_pass http://127.0.0.1:3001/aboutus/; }
        # 静态资源路径转发（CSS/JS/图片）
        location ^~ /css/g/        { proxy_pass http://127.0.0.1:3001/css/g/; }
        location ^~ /img/          { proxy_pass http://127.0.0.1:3001/img/; }
        location ^~ /js/           { proxy_pass http://127.0.0.1:3001/js/; }

        # -------------------- 项目3：默认项目（3000端口） --------------------
        # 根路径转发（未匹配上述路径时，默认指向3000端口项目）
        location / {
            proxy_pass  http://127.0.0.1:3000;
            # 同上：传递Host头，保证登录态共享
            proxy_set_header  Host  $host;
            proxy_set_header  X-Real-IP  $remote_addr;
            proxy_set_header  X-Forwarded-For  $proxy_add_x_forwarded_for;
            proxy_buffering off;
        }
    }
}

配置关键优化说明

优化点	作用
`server_name` 改为 `local.dev.yitong.com`	与 Hosts 映射的域名一致，保证访问域名统一
`proxy_set_header Host $host`	传递真实域名到后端项目，避免项目因识别不到域名导致登录态失效
`proxy_buffering off`	禁用代理缓存，本地开发时修改代码可实时生效
`^~` 路径匹配	优先匹配具体业务路径，避免根路径（`/`）覆盖子路径
替换 `10.10.12.57` 为 `127.0.0.1`	本地开发优先转发到本机端口，而非内网IP（若需转发内网其他机器可保留）

四、第三步：Nginx 启动与验证

1. Nginx 常用命令（Windows CMD）

# 进入Nginx目录（替换为实际路径）
cd E:\Program Files\nginx-1.24.0

# 验证配置文件是否正确（关键！启动前必做）
nginx.exe -t
# 成功提示：nginx: the configuration file ... syntax is ok; test is successful

# 启动Nginx
nginx.exe

# 热重载配置（修改配置后无需重启，直接重载）
nginx.exe -s reload

# 停止Nginx（优雅关闭）
nginx.exe -s stop

# 强制杀死Nginx进程（若优雅关闭失败）
taskkill /f /t /im nginx.exe

2. 启动本地项目并验证

分别启动各项目的本地服务：
- pc-account：运行在 127.0.0.1:3002；
- ytwweb：运行在 127.0.0.1:3001；
- 默认项目：运行在 127.0.0.1:3000；
打开浏览器访问 http://local.dev.yitong.com：
- 访问 http://local.dev.yitong.com/vc3/wx/ → 转发到 3002 端口项目；
- 访问 http://local.dev.yitong.com/goods/ → 转发到 3001 端口项目；
- 访问 http://local.dev.yitong.com/ → 转发到 3000 端口项目；
验证登录态：在任意项目登录后，跳转其他项目路径，登录状态应保持（同域名下 Cookie 共享）。

五、关键注意事项（避坑指南）

1. 登录态共享核心原理

Cookie 是「域名维度」的，Nginx 统一域名后，所有项目的 Cookie 都绑定到 local.dev.yitong.com，因此可共享登录态；
若项目依赖 document.domain 识别域名，需确保项目中配置的域名与 local.dev.yitong.com 一致。

2. Nginx 配置常见问题

proxy_pass 斜杠问题：proxy_pass 末尾加 / 表示转发时去掉匹配的路径前缀，不加则保留。例如：
- location /goods/ + proxy_pass http://127.0.0.1:3001/ → 访问 /goods/123 转发到 3001/123；
- location /goods/ + proxy_pass http://127.0.0.1:3001/goods/ → 访问 /goods/123 转发到 3001/goods/123（推荐）。
端口占用：若 80/443 端口被占用（如 IIS、Apache），可修改 listen 端口（如 listen 8080），访问时用 local.dev.yitong.com:8080。

3. 证书配置注意事项

若无需 HTTPS 访问，可注释 ssl_certificate 相关配置，仅使用 80 端口；
本地测试证书可通过 mkcert 生成（避免浏览器提示不安全）。

总结

1. 核心流程

Hosts 映射：自定义域名 → 127.0.0.1；
Nginx 反向代理：统一域名的不同路径 → 对应项目端口；
启动验证：统一域名访问多项目，共享登录态/缓存。

2. 关键点回顾

必须保证 server_name 与 Hosts 配置的域名一致，否则登录态无法共享；
proxy_set_header Host $host 是登录态共享的核心配置，不可省略；
本地开发禁用 Nginx 代理缓存（proxy_buffering off），避免代码修改不生效；
修改 Nginx 配置后，优先用 reload 热重载，而非重启。

通过这套配置，可完美模拟线上「单域名多项目」的访问体验，解决本地跨端口开发的登录态隔离、路径跳转问题，大幅提升多项目集成开发效率。

#nginx

nginx代理实践（一）多项目本地联调

https://cszy.top/20201120-nginx-0/

作者

csorz

发布于

2020年11月20日

许可协议

SSH & FTP工具上一篇

使用Github的webhook完成自动部署网站下一篇