用任务运行器统一管理项目命令

在不同项目之间切换时，最容易浪费时间的往往不是写代码，而是回忆命令：这个项目用 npm 还是 pnpm？测试要先启动数据库吗？Java 项目是执行 mvn test 还是 ./gradlew test？部署到测试环境前还要不要先跑迁移？

这些命令本身并不难，难的是它们在每个仓库里都不一样。可以把项目内部的细节包起来，对外只暴露一套稳定的入口，例如：

run install
run build
run check
run test
run deploy-staging

这类工具通常被称为任务运行器（task runner）。本文参考 Ham Vocke 对任务运行器的介绍，用几个常见方案说明它们适合解决什么问题。

任务运行器解决什么问题

任务运行器不是要替代 npm scripts、Gradle、Cargo 或其他构建工具，而是在它们之上增加一层稳定的项目接口。

例如，Node.js 项目内部可能是这样：

npm ci
npm run build
npm run lint
npx prettier --write .
npm run test:unit && npm run test:e2e

把这些细节放进任务运行器后，开发者只需要记住：

run install
run build
run lint
run format
run test

以后把包管理器从 npm 换成 pnpm，或者把端到端测试从 Playwright 换成其他工具，只需要修改任务定义，不需要让所有人重新记一遍命令。

方案一：一个简单的 Bash 脚本

如果项目只需要几个任务，Bash 脚本通常已经足够。可以在仓库根目录创建一个名为 run 的文件：

#!/usr/bin/env bash
set -euo pipefail

usage() {
  cat <<'EOF'
用法：./run <task>

可用任务：
  install  安装依赖
  build    构建项目
  lint     检查代码
  format   格式化代码
  test     运行测试
EOF
}

case "${1:-help}" in
  help)
    usage
    ;;
  install)
    npm ci
    ;;
  build)
    npm run build
    ;;
  lint)
    npm run lint
    ;;
  format)
    npx prettier --write .
    ;;
  test)
    npm run test:unit
    npm run test:e2e
    ;;
  *)
    echo "未知任务：$1" >&2
    usage
    exit 1
    ;;
esac

然后赋予执行权限：

chmod +x run

之后就可以用 ./run build 或 ./run test 执行任务。也可以把脚本放进 bin/ 目录，或者把文件名换成更短的 r，根据团队习惯决定即可。

Bash 的优点是几乎到处都有、表达能力强，适合处理条件判断、环境检查、启动多个服务等稍复杂的流程。缺点也很明显：参数转义和错误处理比较容易写错，脚本变大后维护体验会迅速下降。

方案二：Make

make 是更传统的选择。它通常已经预装在开发机和 CI 环境中，项目根目录放一个 Makefile 就能使用：

.PHONY: help install build lint format test

help:
	@echo "make install|build|lint|format|test"

install:
	npm ci

build:
	npm run build

lint:
	npm run lint

format:
	npx prettier --write .

test:
	npm run test:unit
	npm run test:e2e

调用方式变成：

make install
make test
make format

这里有两个容易踩坑的地方。

第一，命令前必须是 Tab，不能用空格。第二，像 install、test 这种只代表动作、不产生同名文件的目标，最好声明为 .PHONY。否则当项目目录里恰好出现一个名为 test 的文件时，Make 可能会认为目标已经是最新状态，从而不执行命令。

Make 的强项其实是文件依赖和增量构建，例如根据源文件是否变化来决定是否重新编译。如果只是想把命令起几个别名，它的功能会显得偏重，但在已有 Make 工作流的团队里非常实用。

方案三：just

just 可以看作更专注于“运行任务”的 Make。它保留了类似 Make 的调用方式，同时去掉了 .PHONY 和 Tab 缩进等一些容易出错的历史包袱。

在仓库根目录创建 justfile：

default:
    @just --list

install:
    npm ci

build:
    npm run build

lint:
    npm run lint

format:
    npx prettier --write .

test:
    npm run test:unit
    npm run test:e2e

使用时输入：

just build
just test

just --list 可以列出任务。在任务前加文档注释，列表会更容易阅读：

# 构建项目
build:
    npm run build

它很适合新项目：语法简单，文件也容易读懂。需要注意的是，Bash 和 Make 往往已经存在于系统中，而 just 通常需要额外安装。团队采用前，最好把安装方式写进项目文档或开发环境初始化脚本。

方案四：mise

如果项目不只需要任务，还需要统一 Node、Python、Java 等工具版本，或者需要管理环境变量，那么 mise 会更合适。它可以把工具版本、环境配置和任务放在一个项目级配置里。

一个简单的 mise.toml 如下：

[tasks.install]
description = "安装依赖"
run = "npm ci"

[tasks.build]
description = "构建项目"
run = "npm run build"

[tasks.check]
description = "执行静态检查和格式检查"
run = ["npm run lint", "npx prettier --check ."]

[tasks.test]
description = "运行单元测试和端到端测试"
run = ["npm run test:unit", "npm run test:e2e"]

调用方式是：

mise run build
mise run check
mise run test

当项目已经在使用 mise 管理运行时版本时，把任务也放进 mise.toml 可以减少配置文件数量。不过，如果项目只需要五六个简单命令，单独引入 mise 可能会增加学习和安装成本。

怎么选

可以按下面的顺序做决定：

• 只有几个包装命令：先用 Bash。
• 已经有 Makefile：继续用 Make，不必为了新潮而迁移。
• 新项目只想要一个好读的任务文件：优先考虑 just。
• 还要锁定运行时版本和环境变量：考虑 mise。

任务命名比工具更重要

选择工具只是第一步，任务名称和边界才是长期维护的关键。建议遵循几个原则。

对外暴露稳定的名字

任务名描述意图，不要暴露实现细节。例如用 format，而不是 prettier-write；用 db-migrate，而不是某个具体 ORM 的命令。这样底层工具替换时，调用方无需变化。

区分检查和修改

format 可以修改文件，format-check 只检查格式；lint 检查代码，fix 才执行自动修复。名称清楚后，开发者和 CI 就不容易误操作。

让本地和 CI 共用入口

CI 不要复制一份复杂命令：

steps:
  - run: ./run install
  - run: ./run check
  - run: ./run test
  - run: ./run build

这样本地复现 CI 失败会简单很多，也能避免“本地能过、CI 不能过”只是因为调用命令不一致。

对危险操作增加保护

部署生产、清空数据库、删除对象存储等任务不应该只靠一个容易输错的短命令。可以在任务中检查环境变量、要求显式确认，或者把生产部署拆成单独的脚本并限制权限。

例如，部署任务至少应该拒绝明显错误的环境：

if [[ "${APP_ENV:-}" != "staging" ]]; then
  echo "只能在 staging 环境运行此任务" >&2
  exit 1
fi

结语

任务运行器解决的是一个很小、但每天都会遇到的问题：不要把精力花在回忆命令和参数上。它不需要复杂的架构，先把安装、检查、测试、构建这几个高频动作统一起来就有收益。

我的建议是从项目根目录的一份任务文件开始，保持任务少而清楚，并让本地和 CI 调用同一套入口。项目变复杂后，再根据需要从 Bash 演进到 Make、just 或 mise，而不是一开始就引入一整套工具链。