pm2 restart は動くのに start で失敗する理由

はじめに

Node.js のプロセスマネージャーとしてよく使われる PM2。
便利なのですが、初心者がよくハマる落とし穴のひとつに「restart は動くのに start が失敗する」という現象があります。

現象

• pm2 restart ecosystem.config.js → 正常に動く
• pm2 start ecosystem.config.js → 「Script not found」などのエラーで落ちる

理由

• restart は すでに登録済みのプロセス情報 をもとに動作する
  • pm2 list に残っている設定を参照してプロセスを再起動するだけ
• 一方 start は 指定されたファイルから新規に起動しようとする
  • ecosystem.config.js の script のパスが正しくないと失敗する

つまり、「restart で動く = 以前に正しいパスで起動した履歴が残っている」だけで、
start ではパス解決が再度チェックされるためエラーになります。

よくある原因

1. script の相対パスがずれている
   • dist/main.js なのか example/dist/main.js なのか混乱しやすい
2. ecosystem.config.js を置いているディレクトリが違う
   • pm2 start を実行したカレントディレクトリと script のパスが噛み合わない
3. ビルドを忘れている
   • TypeScript をビルドして dist/ がない状態で start している

対処法

• pm2 start ecosystem.config.js の前に必ず ビルドを確認
• script はできるだけ 絶対パス を書くと混乱が減る
• カレントディレクトリを固定したいなら、cwd オプションを設定するのも有効

ecosystem.config.js の例

module.exports = {
  apps: [
    {
      name: "example-app",
      script: "./dist/main.js",
      cwd: "/home/ubuntu/example",
      instances: "max",
    },
  ],
};