concurrently 并发执行命令完整指南：从 CLI 到编程式 API 的实战与源码解析

CLI开发工具【免费下载链接】concurrentlyRun commands concurrently. Like npm run watch-js npm run watch-less but better.项目地址https://gitcode.com/gh_mirrors/co/concurrently点击查看免费下载concurrently是一个跨平台的 Node.js 命令行工具用于同时运行多个命令并统一管理它们的输出、退出码与生命周期。本文以仓库 README.md 为核心脉络结合 bin/index.tsCLI 入口、lib/concurrently.ts核心调度、lib/index.tsAPI 组装与 lib/command.ts命令抽象等源码系统讲解从安装、命令行使用、快捷语法到编程式 API 的完整方案并深入说明其底层执行流程帮助你像npm run watch-js npm run watch-less一样并行任务却获得带前缀的可读日志、失败联动终止与进程重启等更强能力。背景与动机为什么需要 concurrently在 npm 生态中并行运行任务的常规操作是npm run watch-js npm run watch-css。它虽然可行但存在两个明显痛点见 README.md 的 Why 一节输出难以区分多个进程的输出混在一起无法快速对应到具体命令失败无感知某个进程挂掉后其他进程仍在运行你甚至不会注意到差异。另一个选择是开多个终端窗口但这显然低效。concurrently 正是为解决这类问题而生它宣称的核心特性包括跨平台含 Windows输出易于追踪通过前缀prefix区分各命令的输出联动终止配合--kill-others开关一个命令死亡时终止其余所有命令。工具本身是 Node.js 写的但可以运行任意语言的命令。安装方式concurrently 支持全局安装整个系统可用或本地安装用于某个包的scripts段各包管理器命令如下摘自 README.mdnpmYarnpnpmBun全局npm i -g concurrentlyyarn global add concurrentlypnpm add -g concurrentlybun add -g concurrently本地*npm i -D concurrentlyyarn add -D concurrentlypnpm add -D concurrentlybun add -d concurrently* 官方建议将 concurrently 装进devDependencies因为它通常只用于开发场景若你的场景不适用请自行调整命令。从 package.json 可以看到发布版本同时暴露两个二进制别名concurrently与conc即 CLI 下二者等价。CLI 快速上手命令语法与引号规则基础用法是把多条命令作为参数依次传入README.mdconcurrently command1 arg command2 arg务必用引号包裹每条命令。如果不加引号concurrently 会把空格拆分成独立参数例如concurrently command1 arg command2 arg会被当成 4 条命令执行command1、arg、command2、arg。⚠️Windows 注意Windows 只支持双引号concurrently command1 arg command2 arg且在 package.json 中写脚本时需要转义双引号start: concurrently \command1 arg\ \command2 arg\任何时刻可以用concurrently --help查看全部可用选项用concurrently --version查看版本bin/index.ts 中注册了-h/--help、-v/-V/--version。更系统的用法文档见 docs 目录。核心命令行选项一览以下选项均来自 bin/index.ts 的 yargs 定义按功能分组整理通用General选项别名说明--max-processes-m同时运行的最大进程数支持具体数字或 CPU 百分比如50%设为 1 即串行--names-n自定义名称列表用于前缀模板如main,browser,server--success-s成功条件取值first第一个退出的决定成败、last最后一个退出的决定成败、all全部成功、command-{name}/command-{index}指定名称/序号、!command-{name}/!command-{index}除指定之外默认all--raw-r仅输出进程原始输出禁用美化与前缀着色--no-color禁用日志颜色Chalk 会自行读取并移除颜色--hide逗号分隔的进程列表按名称或序号以隐藏输出--group-g让输出看起来像命令被串行执行时的顺序--timings显示所有进程的运行时间信息--shell运行命令的 shell默认 Windows 下cmd.exe其他平台/bin/sh详见 shell resolution--passthrough-arguments-P将附加参数透传给命令通过占位符访问而不是当作新命令--teardown退出前执行的清理命令可指定多次这些命令不加前缀、不影响 concurrently 的退出码前缀样式Prefix styling选项别名说明--prefix-p日志前缀类型index、pid、time、command、name、none或模板如{time}-{pid}默认使用进程名未设置名称时用序号--prefix-colors-c逗号分隔的 Chalk 颜色列表如red,green、#23de43命令多于颜色时重复最后一个支持auto自动选色--prefix-length-l前缀使用command类型时最多显示的字符数默认10--pad-prefix用空格补齐短前缀使所有前缀长度一致--timestamp-format-t时间前缀的 Unicode 格式默认yyyy-MM-dd HH:mm:ss.SSS终止其他进程Killing other processes选项别名说明--kill-others-k第一个进程退出后终止其余进程--kill-others-on-fail某进程以非零状态退出时终止其余进程--kill-signal-ks向被杀进程发送的信号SIGTERM/SIGKILL默认 SIGTERM--kill-timeout等待多少毫秒后强制终止进程重启Restarting选项说明--restart-tries进程挂掉后的重启尝试次数默认0负数表示无限重启--restart-after重启前等待的毫秒数或字符串exponential指数退避默认0输入处理Input handling选项别名说明--handle-input-i是否将标准输入转发给子进程--default-input-target未在输入开头指定目标时stdin 默认发送给的进程标识序号或名称默认0这些默认值集中定义在 lib/defaults.ts 中如prefix 、prefixColors auto、restartTries 0、success all等CLI 与库共用同一份配置基准。用环境变量固化配置如果希望某些标志常驻可以借助环境变量任何 concurrently 选项都可通过以CONCURRENTLY_为前缀的环境变量设置详见 docs/cli/configuration.md$ export CONCURRENTLY_KILL_OTHERStrue $ export CONCURRENTLY_HANDLE_INPUTtrue # 等价于每次传入 --kill-others 与 --handle-input $ concurrently nodemon echo hey nodemon, you wont last long其原理是 bin/index.ts 调用了 yargs 的.env(CONCURRENTLY)自动从同名环境变量读取参数。命令快捷方式与通配符npm:等快捷语法concurrently 内置命令解析器parser把形如npm:script的简写展开为完整命令。展开规则定义在 lib/command-parser/expand-shortcut.ts语法展开为npm:scriptnpm run scriptpnpm:scriptpnpm run scriptyarn:scriptyarn run scriptbun:scriptbun run scriptnode:scriptnode --run scriptdeno:scriptdeno task script例如 API 示例中的npm:watch-*即会被解析为npm run watch-*并自动以脚本名作为进程名若未显式指定 name。通配符展开与排除lib/command-parser/expand-wildcard.ts 负责把npm run、yarn run、pnpm run、bun run、node --run、deno task中的通配符*展开为当前目录下所有匹配的脚本脚本清单来自package.json的scripts字段deno task则合并deno.json/deno.jsonc的tasks与 npm scripts支持(!name)语法排除匹配项如npm:watch-*:(!watch-css)若通配符命中为空前缀可能为空字符串此时以序号兜底。例如concurrently npm:watch-*会为watch-js、watch-css等每个匹配脚本各生成一条命令并行运行。透传附加参数Passthrough Arguments配合--passthrough-arguments或-P--之后的参数会作为附加参数注入命令而不是当作新命令。占位符规则见 lib/command-parser/expand-arguments.ts 与 docs/cli/passthrough-arguments.md{1}、{2}…对应第 1、2 个附加参数{}全部附加参数逐个引号包裹后展开{*}全部附加参数合并为一个字符串占位符可用\{1}转义以输出字面量若对应参数不存在占位符被替换为空字符串。concurrently -P npm:dev-{1} -- --watch编程式 APIconcurrently 不仅提供 CLI也提供完整的编程式接口便于在 Node.js 脚本或工具中集成。concurrently(commands[, options])commands字符串数组或形如{ command, name, prefixColor, env, cwd, ipc }的对象数组。options可选对象完整字段与默认值如下摘自 README.md 及 lib/index.tscwd所有命令的默认工作目录可被单条命令覆盖。默认process.cwd()。shell执行命令字符串所用的 shell未设置时优先使用npm_config_script_shell如经npm run运行时否则 Windows 用cmd.exe、其他平台用/bin/sh见 docs/shell-resolution.md。defaultInputTarget从inputStream读取输入时的默认输入目标。默认0。handleInput为true时从process.stdin读取输入。inputStream自定义的 Readable 流 作为输入源仅在需要从非 stdin 流读取的罕见场景使用且会覆盖handleInput。pauseInputStreamOnFinish默认在所有进程结束后暂停输入流process.stdin或inputStream若需在 concurrently 结束后继续读取输入流设为false。killOthersOn第一个命令以这些状态退出时终止其他命令可含success退出码 0和/或failure非零退出码。maxProcesses同时运行的进程数上限支持数字或 CPU 百分比字符串如50%由 lib/concurrently.ts 换算为实际进程数。outputStream日志写入的 Writable 流。默认process.stdout。prefix日志前缀类型取值index、pid、time、command、name、none或模板如[{time} process: {pid}]默认取进程名无名称时用序号。模板支持用{color}与{/color}包裹局部着色如[{color}{name}{/color}]只给名称上色。prefixColorsChalk 支持的颜色列表或字符串外加auto自动选色支持#RRGGBB、bg#RRGGBB、hex()、bgHex()、rgb()、bgRgb()、ansi256()、bgAnsi256()且函数与修饰符可链式组合如rgb(255,136,0).bold、black.bgHex(#00FF00).dim命令数多于颜色数时重复最后一个颜色最后一个为auto则后续自动挑色以保持变化单条命令指定的prefixColor优先级高于此列表。设为false可完全禁用颜色。prefixLength前缀为command类型时显示的字符数。默认10。raw原始模式只记录进程原始输出无前缀、着色等任何附加内容可被单条命令覆盖。successCondition运行成功的判定条件。first只由第一个退出的进程决定成败last由最后一个退出的进程决定其他值如all要求所有进程成功退出。另支持command-{name}/command-{index}及其取反形式。restartTries进程死亡后的重启尝试次数。默认0。restartDelay两次重启之间的等待毫秒数。默认0CLI 端还支持exponential指数退避。timestampFormattime前缀使用的 Unicode 日期格式。默认yyyy-MM-dd HH:mm:ss.SSS。additionalArguments附加参数列表会替换命令中的占位符未定义则不做参数替换。返回形如{ result, commands }的对象result一个 Promise按successCondition成功时 resolve失败时 reject值均为按命令终止顺序排列的CloseEvent数组commands所有已生成Command对象的数组。完整示例README 中的经典示例此处以 CommonJS 展示并保留占位注释说明各字段用途const concurrently require(concurrently); const { result } concurrently( [ npm:watch-*, // 快捷语法展开为 npm run watch-*并匹配 package.json 中所有 watch-* 脚本 { command: nodemon, name: server }, { command: deploy, name: deploy, env: { PUBLIC_KEY: ... } }, // 覆盖环境变量 { command: watch, name: watch, cwd: path.resolve(__dirname, scripts/watchers), // 覆盖工作目录 }, ], { prefix: name, killOthersOn: [failure, success], restartTries: 3, cwd: path.resolve(__dirname, scripts), }, ); result.then(success, failure);底层对字符串命令的解析名称/环境/工作目录归一化、前缀颜色分配由 lib/concurrently.ts 的mapToCommandInfo完成字符串会被视为{ command }未命名的命令以空字符串为名最终前缀颜色由PrefixColorSelector依次分配。Command 对象Command封装了单个生成进程的全部信息与交互方式实现见 lib/command.ts属性如下index该命令在所有命令中的序号command命令的命令行字符串name命令名称默认空字符串cwd命令的工作目录env命令生成时携带的全部环境变量对象killed命令是否已被终止state命令状态取值stopped从未启动、started运行中、errored生成失败、exited已退出如收到 close 事件pid进程 IDstdin通往命令stdin的 Writable 流stdout命令stdout的 RxJS 可观察流stderr命令stderr的 RxJS 可观察流error命令错误事件如生成失败的 RxJS 可观察流timer命令计时事件启动、停止的 RxJS 可观察流stateChangestate属性变化的 RxJS 可观察流messages包含incoming收到的 IPC 消息与outgoing发出的 IPC 消息两个 RxJS 可观察流均发射MessageEvent若命令未启用 IPC则不会产生任何值close命令 close 事件的 RxJS 可观察流详见CloseEventstart()启动命令并建立上述各流send(message[, handle, options])通过 IPC 通道向底层进程发送消息返回在消息送达后 resolve 的 Promise对应 Node.jschild_process的subprocess.send语义kill([signal])终止命令可选指定信号如SIGTERM、SIGKILL。从实现看Command.start()内部会记录启动时间、订阅error/close事件、把stdout/stderr的data事件桥接到对应的 Subject并在close时计算durationSeconds精确耗时lib/command.ts。kill()默认走tree-kill模块可连同子进程树一起终止。MessageEvent表示从/向底层命令进程收发消息的事件对象lib/command.tsmessage消息本体handle若随消息发送了句柄则为net.Socket、net.Server或dgram.Socket否则为undefined。启用方式是在命令对象中指定ipc文件描述符号必须大于 2例如{ command: node server.js, ipc: 3 }对应 Node.js 端会建立 IPC 通道。CloseEvent描述命令关闭事件的对象lib/command.tscommand精简版Command仅含name、command、env、cwdindex命令在所有命令中的序号killed命令是否因被终止而退出exitCode进程退出码或因信号终止时的信号名timings形如{ startDate, endDate, durationSeconds }的计时信息。resultPromise 的 resolve/reject 值就是按终止顺序排列的CloseEvent[]。常见问题 FAQ进程以代码null退出按 Node.jschild_process的exit事件语义进程正常终止时code为最终退出码否则为null若进程因收到信号而终止signal为信号名字符串否则为null。因此null意味着进程非正常终止concurrently 也会随之返回非零退出码。能配合 yarn / pnpm / Bun 使用吗可以。上述所有示例中的npm均可替换为yarn、pnpm或bun包括npm:快捷语法对应的yarn:、pnpm:、bun:前缀见 expand-shortcut.ts。从源码看整体执行流程理解核心调度有助于调试与二次开发。从 lib/concurrently.ts 与 lib/index.ts 可以勾勒出如下流程校验与归一化断言commands是非空数组lib/concurrently.ts随后用mapToCommandInfo把字符串/对象统一为CommandInfo命令解析链依次应用ExpandShortcut快捷语法、ExpandWildcard通配符若配置了附加参数再加入ExpandArguments占位符替换每个 parser 都可能把一条命令展开为多条lib/concurrently.ts生成 Command按解析结果创建Command实例分配前缀颜色、按hide/raw决定 stdio 模式隐藏输出或原始模式并依据每条命令或全局的cwd/env构造 spawn 选项lib/concurrently.tsFlow Controller 管线lib/index.ts把LogError、LogOutput、LogExit、InputHandler、KillOnSignal、RestartProcess、KillOthers、OutputErrorHandler、LogTimings、Teardown等控制器按顺序挂到命令上lib/index.ts它们以 reducer 方式逐一对命令集做变换与订阅实现日志、输入转发、重启、联动终止、超时清理等能力并发调度根据maxProcesses支持 CPU 百分比换算启动前 N 个命令每个命令close后再从队列拉取下一个实现有界并发maxProcesses: 1即串行lib/concurrently.ts成功判定CompletionListener按successCondition监听各命令的关闭事件最终决定resultPromise 的成败lib/concurrently.tsCLI 端据此以process.exit(0/1)结束bin/index.ts。整体默认值maxProcesses 0表示不限、raw false、timestampFormat yyyy-MM-dd HH:mm:ss.SSS等统一维护在 lib/defaults.ts被 CLI、API 与 flow controller 共享。仓库还提供 lib/concurrently.spec.ts、lib/command.spec.ts 及各 flow controller 的 spec 测试如 kill-others.spec.ts、restart-process.spec.ts可作为理解各行为边界的权威参考。延伸阅读仓库的 docs 目录 按主题组织更细粒度的指南均适用于 CLI 与 APIShell 解析规则npm_config_script_shell、Windowscmd.exe与 Unix/bin/sh的选择逻辑前缀配置 与 输出控制前缀模板、颜色、原始模式与输出分组成功条件first/last/all/command-{name}等判定语义快捷方式 与 透传参数命令简写与{1}、{}占位符终止命令、重启命令、输入处理 与 配置方式对应--kill-*、--restart-*、--handle-input与CONCURRENTLY_*环境变量。赞分享CLI开发工具【免费下载链接】concurrentlyRun commands concurrently. Like npm run watch-js npm run watch-less but better.项目地址https://gitcode.com/gh_mirrors/co/concurrently点击查看免费下载相关推荐Relay commitMutation 完整指南命令式执行 GraphQL Mutation 的 API 详解与源码剖析Relay commitMutation 完整指南命令式执行 GraphQL Mutation 的 API 详解与源码剖析 commitMutation 是前端开发工具concurrently 官方文档完全指南CLI 与 API 全场景并发命令管理concurrently 官方文档完全指南CLI 与 API 全场景并发命令管理 本篇技术指南以 concurrently 官方文档体系 docs/READCLI开发工具rbenv 源码分析从入口到命令分发的完整执行流程rbenv 源码分析从入口到命令分发的完整执行流程 rbenv 是一个轻量级的 Ruby 版本管理工具通过巧妙的架构设计实现了高效的版本切换和环境管理。本文开发工具CLI上一篇JupyterLab Variable Inspector 常见问题解决方案下一篇10个让React-Archer箭头绘制化繁为简的实战方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考