Java ProcessBuilder 怎样读取子进程退出码

Java 用 ProcessBuilder 启动外部命令时，退出码不在 start() 返回值里，而是在得到 Process 后等待进程结束，再调用 waitFor() 或 exitValue() 读取。通常退出码为 0 表示命令按自己的约定成功，非 0 只能说明命令报告了失败，具体含义仍要结合命令文档和输出判断。

如果还要读取命令输出，先决定 stdout 和 stderr 是分开保留，还是通过 redirectErrorStream(true) 合成一条流。这个选择会影响读取代码、错误日志的区分方式和发生阻塞的风险。

官方资料：https://docs.oracle.com/en/java/javase/26/docs/api/java.base/java/lang/ProcessBuilder.html

先把启动和退出分成两个阶段

ProcessBuilder 是启动配置对象，保存命令参数、工作目录、环境变量以及输入输出重定向；start() 才会尝试创建操作系统进程。创建失败通常以 IOException 暴露，不能把这类异常当成某个外部命令的退出码。

启动成功后拿到的是 Process。它代表已经创建的子进程，也提供三个方向的流：Java 写入子进程标准输入的 getOutputStream()，读取子进程标准输出的 getInputStream()，以及读取标准错误的 getErrorStream()。

用 waitFor 等待结束并读取退出码

最小做法是先调用 start()，再调用 waitFor()。前者负责启动，后者会阻塞当前线程直到子进程结束，并直接返回退出码。此时不需要再调用 exitValue()，因为 waitFor() 已经给出了同一个结果。

import java.io.IOException;

public class ReadExitCode {
    public static void main(String[] args) {
        try {
            // 命令和参数分开传入，避免把整行命令交给 shell 重新解析。
            ProcessBuilder builder = new ProcessBuilder("java", "-version");
            // start 只负责创建进程；成功后才有 Process 对象可以等待。
            Process process = builder.start();
            // waitFor 等待子进程结束，并返回命令报告的退出码。
            int exitCode = process.waitFor();
            System.out.println("exitCode=" + exitCode);
        } catch (IOException ex) {
            // IOException 表示进程没有正常创建或启动，不是子进程退出码。
            System.err.println("无法启动命令：" + ex.getMessage());
        } catch (InterruptedException ex) {
            // 等待线程被中断时恢复中断标记，把取消信号交给上层处理。
            Thread.currentThread().interrupt();
            System.err.println("等待子进程时被中断");
        }
    }
}

这段示例只打印退出码，没有把 java -version 的版本文本当成本文的固定输出。不同 JDK 和平台可能把版本信息写到 stderr，也可能有不同的格式；文章关注的是读取退出码的时机。

waitFor 和 exitValue 有什么区别

waitFor() 可以等待；exitValue() 只适合读取已经结束的进程。如果进程仍在运行，直接调用 exitValue() 会抛出 IllegalThreadStateException。因此可以按下面的原则选择：

如果使用带超时的 waitFor，返回 false 只表示在给定时间内没有结束，不等于进程已经失败。后续可以调用 destroy() 或 destroyForcibly()，但要把“超时后终止”作为业务策略写清楚。

import java.util.concurrent.TimeUnit;

// 只展示超时判断；实际项目还应记录命令上下文并决定是否终止进程。
boolean finished = process.waitFor(10, TimeUnit.SECONDS);
if (!finished) {
    // 超时不是退出码，先终止，再按业务约定记录 timeout 状态。
    process.destroy();
} else {
    // 只有确认结束后，exitValue 才能安全读取。
    int exitCode = process.exitValue();
}

默认双流与合并输出怎么选

默认情况下，标准输出和标准错误分别进入两条管道：getInputStream() 读 stdout，getErrorStream() 读 stderr。这样保留了日志级别和错误来源，适合需要把正常输出与错误输出分别记录的任务。

如果调用 redirectErrorStream(true)，stderr 会并入 stdout，Java 只从 getInputStream() 读取合并结果；此时 getErrorStream() 会变成空输入流，原本的错误分流关系也就不再保留。

合并读取适合只需要一份按到达顺序收集的文本。分开读取时，不能让一个输出管道长期没人消费：如果子进程持续写满未读取的管道，子进程可能停在写操作上，主线程也就迟迟等不到退出。

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;

try {
    // 合并后只消费一个读取端，适合不要求区分 stdout 和 stderr 的小工具。
    ProcessBuilder builder = new ProcessBuilder("java", "-version")
            .redirectErrorStream(true);
    Process process = builder.start();

    // try-with-resources 负责关闭读取端，逐行消费避免一次性拼接全部输出。
    try (BufferedReader reader = new BufferedReader(
            new InputStreamReader(process.getInputStream(), StandardCharsets.UTF_8))) {
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(line);
        }
    }

    // 读取结束后等待进程完成，再判断退出码。
    int exitCode = process.waitFor();
    if (exitCode != 0) {
        throw new IOException("外部命令退出码为 " + exitCode);
    }
} catch (InterruptedException ex) {
    // 中断表示当前等待被取消，恢复标记后不要悄悄吞掉信号。
    Thread.currentThread().interrupt();
}

这里的“合并”只改变 stderr 的去向，不会把退出码自动改成 0。命令仍然可以先输出文本再返回非 0，调用方必须同时保留输出和退出码两个判断维度。

分开读取时补齐异常和资源收尾

需要分开保存 stdout 和 stderr 时，通常让两个读取任务并行消费，再由主线程等待进程结束。示例中的线程池只用于说明读取关系；真实项目可以使用现有的执行器，并给任务设置取消和关闭策略。

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.StandardCharsets;
import java.util.concurrent.ExecutorService;
import java.util.concurrent.Executors;

static void drain(InputStream input, String label) throws IOException {
    // 持续消费指定管道，防止子进程因输出缓冲区写满而停住。
    try (BufferedReader reader = new BufferedReader(
            new InputStreamReader(input, StandardCharsets.UTF_8))) {
        String line;
        while ((line = reader.readLine()) != null) {
            System.out.println(label + ": " + line);
        }
    }
}

ExecutorService readers = Executors.newFixedThreadPool(2);
Process process = null;
try {
    // 不合并两条管道，才能在日志中保留 stdout 和 stderr 的来源。
    process = new ProcessBuilder("java", "-version").start();
    Process current = process;
    readers.submit(() -> {
        try {
            drain(current.getInputStream(), "stdout");
        } catch (IOException ex) {
            // 读取任务的异常不能静默丢失，包装后由 Future 或统一异常处理接住。
            throw new RuntimeException("读取 stdout 失败", ex);
        }
    });
    readers.submit(() -> {
        try {
            drain(current.getErrorStream(), "stderr");
        } catch (IOException ex) {
            // stderr 同样需要报告读取失败，不能只看主线程的退出码。
            throw new RuntimeException("读取 stderr 失败", ex);
        }
    });

    // 主线程等待进程结束；读取任务继续消费两条输出管道。
    int exitCode = current.waitFor();
    System.out.println("exitCode=" + exitCode);
} catch (InterruptedException ex) {
    // 中断时尝试结束子进程，并把中断状态交给上层。
    if (process != null) process.destroy();
    Thread.currentThread().interrupt();
} finally {
    // 读取任务不再需要时关闭执行器，避免后台线程长期存活。
    readers.shutdown();
}

这个片段把读取异常留在读取任务里，工程代码应进一步保存 Future 并检查任务异常，或者把读取封装成能返回结果的任务。不要只判断主线程的退出码就认为两条日志都已经成功落盘。

按任务目标选择实现方式

最后再检查命令参数是否按列表传入、工作目录是否存在、超时后是否销毁进程，以及关闭读取端和执行器。这样才是完整的“读取退出码”处理，而不是只在代码末尾加一句 exitValue()。

常见疑问

调用 start 返回的是什么？返回 Process，不是退出码；退出码要等进程结束后通过 waitFor() 或 exitValue() 获取。

退出码为 0 就代表所有输出都正确吗？不一定。退出码只是外部命令定义的状态，输出文本、文件结果和业务格式仍需单独判断。

redirectErrorStream(true) 后还要读 getErrorStream 吗？不需要用它读取错误文本；错误内容已经合并到 getInputStream()，而 getErrorStream() 会是空输入流。

为什么 waitFor 之后还要关闭流？进程结束不等于 Java 侧所有流对象已经按业务完成收尾。使用 try-with-resources 或明确的 finally，可以避免长时间运行程序中的资源积累。