如何为Express配置Nginx代理BasePath，避免本地与线上路径冲突

这个问题我之前在部署Express应用到Nginx反向代理时也遇到过，刚好有几个无需硬编码前缀的优雅解决方案，分享给你：

方案1：使用环境变量+Express Router（推荐，可控性强） #

核心思路是把所有业务路由挂载到一个独立的Router上，然后根据环境变量决定这个Router的基础路径——本地运行时留空，Nginx代理时设为/app。

修改后的代码如下：

const express = require('express');
const app = express();
const router = express.Router();

// 所有业务路由都定义在router上，不用关心前缀
router.get('/ping', (req, res) => {
  res.send('pong');
});

// 从环境变量读取基础路径，默认是空字符串（本地运行场景）
const basePath = process.env.BASE_PATH || '';
// 将router挂载到指定的基础路径上
app.use(basePath, router);

// 端口也建议从环境变量读取，方便不同环境配置
const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server running on port ${port}, base path: ${basePath || '/'}`);
});

使用方式： #

• 本地开发：直接运行node your-app.js，此时BASE_PATH默认是空，访问http://localhost:3000/ping即可正常返回pong。
• Nginx代理部署：启动应用时指定环境变量BASE_PATH=/app node your-app.js，同时在Nginx配置中将/app路径代理到你的Express端口：

  location /app {
    proxy_pass http://localhost:3000;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
  }
  

  此时访问http://your-domain/app/ping就能正常访问接口了。

方案2：利用Nginx传递的请求头动态适配（无需修改启动命令） #

如果不想通过环境变量区分环境，可以让Nginx在代理请求时传递一个自定义请求头，Express通过这个请求头动态挂载路由前缀。

第一步：修改Nginx配置 #

在代理配置中添加X-Forwarded-Prefix头，告诉Express当前的基础路径：

location /app {
  proxy_pass http://localhost:3000;
  proxy_set_header X-Forwarded-Prefix /app;
  proxy_set_header Host $host;
  proxy_set_header X-Real-IP $remote_addr;
}

第二步：修改Express代码 #

添加一个中间件，读取请求头中的前缀并动态挂载路由：

const express = require('express');
const app = express();

// 动态挂载路由的中间件
app.use((req, res, next) => {
  // 从请求头获取前缀，本地运行时默认是空
  const prefix = req.headers['x-forwarded-prefix'] || '';
  
  // 避免重复挂载路由（防止每次请求都创建新的router）
  const hasMounted = app._router.stack.some(layer => layer.path === prefix);
  if (!hasMounted) {
    const router = express.Router();
    // 在这里定义所有业务路由
    router.get('/ping', (req, res) => {
      res.send('pong');
    });
    app.use(prefix, router);
  }
  next();
});

const port = process.env.PORT || 3000;
app.listen(port, () => {
  console.log(`Server running on port ${port}`);
});

这种方式下，本地访问http://localhost:3000/ping和代理后访问http://your-domain/app/ping都能正常工作，无需修改启动命令。

注意事项 #

• 不管用哪种方案，都建议把所有业务路由统一放到Router中管理，不要直接挂载到app上，这样能保证前缀适配的一致性。
• 方案1的环境变量方式更适合CI/CD部署场景，不同环境可以通过配置环境变量快速切换；方案2更适合需要动态适配不同代理前缀的场景。

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