【Node.js】child_processでコマンドを実行する方法｜exec・execSync・spawnの使い分け

Node.jsからgitやffmpegなどの外部コマンドを実行したいときは、標準のchild_processモジュールを使います。コマンドを実行して結果を受け取ったり、ビルドやデプロイのスクリプトを自動化したりできます。実行方法にはexecSync・exec・spawnの3つがあり、用途によって使い分けます。

つまずきやすいのは、execには出力サイズの上限（maxBuffer）があり、大量の出力でエラーになること、そしてexecSyncはコマンドが失敗（終了コードが0以外）すると例外を投げることです。また、コマンドに外部からの値を埋め込むとシェルインジェクションの危険もあります。この記事では、実機のNode.jsで実際にコマンドを実行しながら、child_processの使い方を整理します。

CPUを活かす並列処理としての使い方はChild Processを使った並列処理、終了コードや環境変数はprocess完全ガイド、出力をファイルに保存するならfsでファイルを読み書きするもあわせて参考になります。

3つの方法と使い分け

まず全体像です。3つの方法は次のように使い分けます。

• execSync：同期実行。すぐ結果がほしい簡単なコマンドに。スクリプト向き。
• exec：非同期実行。出力をまとめて受け取る。中程度の出力まで。
• spawn：ストリーミング。大量出力・長時間処理・リアルタイムに出力を受け取りたいとき。

「短くて結果が小さいならexecSyncかexec、出力が大きい・長く動くならspawn」と覚えると選びやすいです。

execSync（同期・手軽）

もっとも手軽なのがexecSyncです。コマンドを実行し、その出力を戻り値として受け取れます。同期的に動くので、結果を使う処理をそのまま続けて書けます。

const { execSync } = require("node:child_process");

// コマンドを実行し、標準出力を受け取る（戻り値はBuffer → toStringで文字列に）
const version = execSync("node --version").toString().trim();
console.log(version);   // v20.x.x など

// 結果をそのまま使える（同期なので順番に実行される）

実機でも、execSync("node --version")でNode.jsのバージョン文字列が取得できました。戻り値はBuffer（バイト列）なので、.toString()で文字列に変換します。execSyncは処理が終わるまで待つため、ビルドスクリプトのように「コマンドを順番に実行する」用途に向いています。ただし同期実行は、その間ほかの処理が止まる点に注意してください（サーバーの中では避けます）。

exec（非同期・promisify/コールバック）

execは非同期でコマンドを実行します。コールバックで結果を受け取るか、util.promisifyでawaitできる形にして使います。

const { exec } = require("node:child_process");
const { promisify } = require("node:util");
const execAsync = promisify(exec);

// promisify で await できる
const { stdout, stderr } = await execAsync("node -e \"console.log(1 + 2)\"");
console.log(stdout.trim());   // 3

// コールバックで書く場合
exec("node --version", (err, stdout, stderr) => {
  if (err) return console.error(err);
  console.log(stdout.trim());
});

実機でも、promisify(exec)でawait execAsync(...)とすると、stdoutに実行結果（3）が得られました。コールバック版は(err, stdout, stderr)の3引数を受け取り、第1引数のerrでエラーを判定します。非同期なので、サーバーの中など「処理を止めたくない場面」ではexec（やspawn）を使います。

stdout・stderr・終了コード

コマンドの出力には、通常の出力（標準出力stdout）とエラー出力（stderr）があります。execでは両方を別々に受け取れます。execSyncはコマンドが失敗すると例外を投げます。

const { execSync } = require("node:child_process");

// stdout と stderr を分けて受け取る（exec のコールバック）
// exec("コマンド", (err, stdout, stderr) => { ... });

// execSync は終了コードが0以外だと例外を投げる
try {
  execSync("node -e \"process.exit(3)\"");
} catch (e) {
  console.log("失敗:", e.status);   // 3（終了コード）
}

execのmaxBuffer（大量出力の罠）

注意したいのが、exec・execSyncは出力を全部メモリに溜め込むことです。そのためmaxBuffer（既定で約1MB）を超える大量の出力があると、エラーになって結果を受け取れません。

const { execSync } = require("node:child_process");

// 出力が maxBuffer（既定 約1MB）を超えるとエラーになる
try {
  // maxBuffer を小さく設定して再現
  execSync("node -e \"console.log('x'.repeat(2*1024*1024))\"", { maxBuffer: 1024 });
} catch (e) {
  console.log("バッファ超過:", e.code);   // ENOBUFS など
}

// 上限を引き上げる（10MB）
// execSync("コマンド", { maxBuffer: 10 * 1024 * 1024 });

spawn（大量出力・長時間処理）

spawnは、出力をストリーミング（少しずつ流れてくる形）で受け取ります。メモリに溜め込まないため、大量出力や長時間動くコマンドに向いています。リアルタイムに進捗を表示したいときにも使えます。

const { spawn } = require("node:child_process");

// コマンドと引数を「配列で別々に」渡す
const child = spawn("node", ["-e", "console.log('hello')"]);

// 出力が来るたびに少しずつ受け取る
child.stdout.on("data", (data) => {
  process.stdout.write(data);   // リアルタイムに表示
});

child.stderr.on("data", (data) => {
  console.error("エラー出力:", data.toString());
});

// 終了時（終了コードを受け取れる）
child.on("close", (code) => {
  console.log("終了コード:", code);   // 0 など
});

実機でも、spawnで実行したコマンドの出力をstdout.on("data", ...)で受け取り、終了時にcloseイベントで終了コード（0）を取得できました。spawnはコマンド名と引数を配列で分けて渡す（spawn("node", ["-e", "..."]））のが特徴です。出力はイベントとして少しずつ届くため、何GBものログでもメモリを圧迫しません。長時間動くプロセスの進捗をリアルタイムに表示したい場合にも最適です。

const { exec } = require("node:child_process");

// NG: ユーザー入力を exec の文字列に直接埋め込む
const userInput = "file.txt; rm -rf /";   // 悪意ある入力
// exec(`cat ${userInput}`);   // 危険！ rm -rf / まで実行されうる

// OK: spawn でコマンドと引数を分離する（シェルを介さない）
const { spawn } = require("node:child_process");
spawn("cat", [userInput]);   // userInput は1つの引数として安全に扱われる