PM2 运行 Angular SSR 应用的解决方案解析

问题背景

在使用 PM2 管理 Angular 19.0.0 服务端渲染(SSR)应用时，开发者可能会遇到一个典型问题：PM2 显示应用已成功启动并在线，但实际应用并未在指定端口(如4000)上运行。这种情况通常发生在使用 Angular SSR 自动生成的 server.mjs 文件时。

问题根源分析

问题的核心在于 Angular SSR 生成的 server.mjs 文件中使用了 isMainModule 函数来判断当前模块是否为主入口模块。这个函数来自 @angular/ssr 包，其作用是"确定提供的 URL 是否表示主入口点模块"。

然而，PM2 使用了一个容器(Node 进程包装器)来管理 Node 进程。这种架构导致 isMainModule 函数无法正确识别当前模块是否为主模块，因此条件判断失败，服务器监听代码永远不会执行。

解决方案详解

1. 修改 server.mjs 文件

原始代码通常如下：

if (isMainModule(import.meta.url)) {
  const port = process.env['PORT'] || 4000;
  app.listen(port, () => {
    console.log(`Node Express server listening on http://localhost:${port}`);
  });
}

需要修改为：

export function startServer() {
  const port = process.env['PORT'] || 4000;
  app.listen(port, () => {
    console.log(`Node Express server listening on http://localhost:${port}`);
  });
}

const metaUrl = import.meta.url;
const isMain = isMainModule(metaUrl);
const isPM2 = process.env['PM2'] === 'true';

if (isMain || isPM2) {
  startServer();
}

关键改进点：

• 将服务器启动逻辑封装为独立函数
• 添加对 PM2 环境变量的检查
• 使用组合条件判断(isMain 或 isPM2)

2. 创建 PM2 配置文件

需要创建一个 ecosystem.config.js 文件：

module.exports = {
  apps: [{
    name: 'your_app_name',
    script: 'server.mjs',
    env: {
      PM2: "true",
      // 其他环境变量...
    }
    // 其他配置...
  }]
};

3. 启动应用的正确方式

使用以下命令启动应用：

pm2 start ecosystem.config.js

技术原理深入

PM2 作为进程管理器，为了实现进程守护、集群模式等功能，会在 Node 进程外层创建一个包装容器。这种设计虽然提供了强大的管理能力，但也改变了 Node 进程的执行环境，导致一些依赖特定环境假设的代码(如 isMainModule)无法正常工作。

Angular SSR 的 isMainModule 函数通过检查 import.meta.url 来判断当前模块是否为主模块。在普通 Node 执行环境下，这个判断是准确的。但在 PM2 的容器环境下，模块加载机制发生了变化，导致判断失效。

解决方案中引入的 PM2 环境变量标志是一种优雅的变通方法，它既保留了原始功能，又兼容了 PM2 的特殊环境。这种模式在实际开发中很常见，特别是在需要区分不同运行环境的场景下。

最佳实践建议

1. 环境变量管理：除了 PM2 标志外，建议将所有环境相关配置都通过环境变量管理
2. 日志记录：在启动逻辑中添加更详细的日志，便于问题排查
3. 错误处理：增强错误处理逻辑，确保进程异常时能正确退出并被 PM2 重启
4. 配置验证：添加配置验证逻辑，确保必要环境变量都已设置
5. 多环境支持：为不同环境(开发、测试、生产)创建不同的 PM2 配置

总结

通过本文介绍的解决方案，开发者可以顺利地在 PM2 环境下运行 Angular SSR 应用。这个问题的解决不仅适用于 Angular 19.0.0，对于其他使用类似机制的框架也具有参考价值。关键在于理解不同工具的工作原理和交互方式，找到兼容各方的解决方案。