Express.js部署于Phusion Passenger时子路由500错误问题求助

问题根源 #

你遇到的子路由404、静态资源丢失、无日志500错误，本质是本地运行和Passenger部署的路径规则不匹配，加上硬编码路由前缀导致的匹配冲突，和你用express.Router()拆分模块的写法没有关系。

第一步：修复路由匹配逻辑 #

你手动给所有路由加/scoreapp前缀的操作和Passenger的默认转发逻辑冲突：

• 当你在主机面板将应用挂载路径设置为/scoreapp时，Passenger会自动剥离路径前缀，把前缀后的请求路径传给Express。比如访问/scoreapp/auth/login时，Express实际收到的请求路径是/auth/login。
• 你手动给路由加了/scoreapp前缀后，Express只会匹配/scoreapp/*格式的路径，自然无法接收Passenger转发的无前缀请求，就会报Cannot GET错误。
• 根路径/scoreapp能正常访问是Passenger对根路径的特殊转发规则导致的巧合，不代表前缀配置正确。

修复操作 #

1. 删除所有路由上硬编码的/scoreapp前缀，恢复成本地可正常运行的挂载配置，用统一变量管理路径前缀：

// app.js路由挂载部分
var indexRouter = require('./routes/index');
var judgesRouter = require('./routes/judges');
var divisionsRouter = require('./routes/divisions');
var competitorsRouter = require('./routes/competitors');
var entriesRouter = require('./routes/entries');
var competitionRouter = require('./routes/competition');
var scoresRouter = require('./routes/scores');
var authRouter = require('./routes/auth');
var messageRouter = require('./routes/message');

// 本地运行时BASE_PATH为空，部署时通过环境变量设置为/scoreapp
const BASE_PATH = process.env.BASE_PATH || '';
app.use(BASE_PATH + '/', indexRouter);
app.use(BASE_PATH + '/auth', authRouter);
app.use(BASE_PATH + '/judges', judgesRouter);
app.use(BASE_PATH + '/divisions', divisionsRouter);
app.use(BASE_PATH + '/competitors', competitorsRouter);
app.use(BASE_PATH + '/entries', entriesRouter);
app.use(BASE_PATH + '/competition', competitionRouter);
app.use(BASE_PATH + '/scores', scoresRouter);
app.use(BASE_PATH + '/message', messageRouter);

2. 所有拆分的Router文件（比如auth.js、competition.js）里的路径定义不需要改，保持本地运行的写法即可，比如router.get('/login')不需要加任何前缀。
3. 代码里所有写死的路径（比如之前注释掉的重定向地址），不要硬编码/scoreapp，统一拼接BASE_PATH：

// 原来的重定向写法
// res.redirect('/scoreapp/auth/login');
// 改成
res.redirect(BASE_PATH + '/auth/login');

第二步：修复静态资源加载失败 #

静态资源404是因为默认的express.static挂载在站点根路径，没有适配子路径部署规则，同时EJS模板里写死的静态资源绝对路径也指向了根路径。

修复操作 #

1. 修改静态资源挂载配置，同样适配BASE_PATH：

// 找到app.js里原来的静态资源配置
// app.use(express.static(path.join(__dirname, 'public')));
// 改成
app.use(BASE_PATH, express.static(path.join(__dirname, 'public')));

2. 把BASE_PATH注入到模板全局变量，所有EJS文件里引用静态资源时拼接前缀：

// 在app.js里配置模板全局变量
app.locals.basePath = BASE_PATH;

然后修改所有EJS里的静态资源引用，比如：

<!-- 原来的写法 -->
<!-- <link rel="stylesheet" href="/css/main.css"> -->
<!-- 改成 -->
<link rel="stylesheet" href="<%= basePath %>/css/main.css">

3. 部署时在主机的环境变量配置里添加BASE_PATH=/scoreapp，本地运行时不设置这个变量，代码会自动把BASE_PATH设为空字符串，和你之前本地运行的逻辑完全一致，不会出现环境差异问题。

第三步：解决500错误无日志问题 #

Passenger默认不会把Node应用的控制台输出、错误栈直接返回给浏览器或存在你项目的日志文件里，所以你看不到具体报错。

排查操作 #

1. 在app.js的所有路由配置之后添加Express标准错误处理中间件，直接把错误信息返回到页面，方便排查：

// 注意：四个参数的中间件才会被识别为错误处理中间件，参数顺序不能改
app.use((err, req, res, next) => {
  console.error('应用运行错误：', err);
  res.status(500).send(`
    <h1>500 服务内部错误</h1>
    <p>错误信息：${err.message}</p>
    <pre>${err.stack}</pre>
  `);
});

2. 常见的部署后500原因：

• 数据库配置错误：本地用的数据库地址、账号、白名单配置和部署环境不匹配，导致连接失败
• 依赖缺失：部署时没有执行npm install，或者部分依赖的原生模块没有在服务器环境重新编译
• 启动文件配置错误：如果是express-generator生成的项目，启动入口应该是bin/www，不要把app.js设为Passenger的启动文件，会导致端口监听异常

3. 排查完问题后，可以把错误处理中间件改成用户友好的提示，不要对外暴露错误栈。

额外注意事项 #

• 如果你用了cookie-session或者express-session，记得把cookie的path配置为BASE_PATH，不然子路径下cookie无法正常写入，登录逻辑会失效。
• 不要在代码里任何位置硬编码/scoreapp前缀，所有路径都通过BASE_PATH变量拼接，后续如果更换挂载路径，只需要改环境变量即可，不需要动业务代码。

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