深入解析npm-run-all的Node API使用

深入解析npm-run-all的Node API使用

npm-run-all A CLI tool to run multiple npm-scripts in parallel or sequential. 项目地址: https://gitcode.com/gh_mirrors/np/npm-run-all

npm-run-all是一个强大的工具，它允许开发者在Node.js环境中以顺序或并行方式运行多个npm脚本。本文将重点介绍npm-run-all的Node API接口，帮助开发者更好地在代码中集成和使用这个工具。

基本使用方法

npm-run-all的Node API提供了一个runAll函数，可以通过简单的require引入：

const runAll = require("npm-run-all");

顺序执行示例

runAll(["clean", "lint", "build:*"], {parallel: false})
    .then(() => console.log("所有任务完成!"))
    .catch(err => console.error("执行失败:", err));

并行执行示例

runAll(["build:* -- --watch"], {parallel: true})
    .then(() => console.log("并行任务完成!"))
    .catch(err => console.error("并行执行失败:", err));

runAll函数详解

runAll函数接受两个参数：脚本模式(patterns)和配置选项(options)。

参数说明

1. patterns：可以是字符串或字符串数组，用于指定要运行的脚本名称模式

   • 支持glob-like模式匹配（如build:*）
   • 可以包含参数（如build -- --watch）

2. options：配置对象，包含丰富的控制选项

常用配置选项

执行控制选项

• parallel：布尔值，是否并行执行（默认false）
• continueOnError：布尔值，出错时是否继续执行后续脚本（默认false）
• maxParallel：数字，并行执行的最大任务数（仅在parallel为true时有效）
• race：布尔值，任一任务成功即终止所有任务（仅在parallel为true时有效）

输出控制选项

• aggregateOutput：布尔值，是否聚合输出以避免交错（仅在parallel为true时有效）
• printName：布尔值，是否在运行每个任务前打印任务名
• printLabel：布尔值，是否在每行输出前添加任务名前缀
• silent：布尔值，是否静默npm的输出日志

流控制选项

• stdin：可读流，作为子进程的标准输入
• stdout：可写流，接收子进程的标准输出
• stderr：可写流，接收子进程的标准错误

其他选项

• npmPath：字符串，指定npm路径
• packageConfig：对象，用于覆盖package.json配置
• taskList：字符串数组，指定所有可用脚本名称（默认从当前目录的package.json读取）

结果处理

runAll返回一个Promise对象，成功时会返回一个结果数组，每个元素包含：

• name：脚本名称
• code：退出代码（未执行则为undefined）

runAll(["test", "lint"])
    .then(results => {
        results.forEach(({name, code}) => {
            console.log(`${name}退出代码: ${code}`);
        });
    });

高级注意事项

关于MaxListenersExceededWarning

在并行模式下使用流选项时，需要注意事件监听器的数量限制：

1. 如果使用了stdin、stdout或stderr选项，需要适当设置最大监听器数量
2. 当process.stdXXX.isTTY为false时，npm-run-all会使用管道连接子进程，此时也需要配置最大监听器

参数替换功能

通过options.arguments数组可以实现参数替换：

runAll(["test-{1}", "build-{2}"], {
    arguments: ["unit", "prod"]
});
// 相当于运行 test-unit 和 build-prod

实际应用场景

1. 构建流程自动化：将清理、编译、测试等步骤按顺序串联
2. 多环境构建：并行构建不同环境版本
3. 监控模式：同时启动多个服务的监控脚本
4. 复杂测试：并行运行单元测试和集成测试

通过npm-run-all的Node API，开发者可以更灵活地在代码中控制npm脚本的执行流程，实现复杂的构建和测试场景。

npm-run-all A CLI tool to run multiple npm-scripts in parallel or sequential. 项目地址: https://gitcode.com/gh_mirrors/np/npm-run-all