just 命令运行器实战指南:用 justfile 保存并运行项目专属命令

原创2026-09-29 11:28:581,852 阅读
文章标签:CLI开发工具任务调度

just 命令运行器实战指南:用 justfile 保存并运行项目专属命令

just 是一款用 Rust 编写的命令行运行器(command runner),它以 make 为灵感、却规避了 make 的大量怪癖,让你把项目特有的命令以"配方(recipe)"的形式保存在 justfile 中,随时一键调用。本指南以 etc/crates-io-readme.md 为核心骨架,结合仓库源码与 README.md、examples 目录下的真实示例,系统讲解从安装、快速上手到配方参数、依赖、跨平台脚本、模块组织的完整方案,读完你就能为自己的项目写出一份专业、可维护的 justfile。

justfile 示例与  输出

上图左侧是 justfile 中定义的配方(build、test-all、带参数的 test TEST 及别名 b),右侧终端执行 just -l 后按文档注释列出了所有可用配方——这正是 just 日常使用的典型场景。

什么是 just,它解决什么问题

just 的核心定位是一句话:便捷地保存并运行项目专属命令。命令存储在名为 justfile(或 Justfile)的文件中,语法受 make 启发,例如 crates-io 简介中的经典示例:

build:
    cc *.c -o main

# test everything
test-all: build
    ./test --all

# run a specific test
test TEST: build
    ./test --test {{TEST}}

与 make 这类构建系统不同,just 是命令运行器而非构建系统,因此规避了 make 大量复杂的固有怪癖——最典型的是无需 .PHONY 声明(因为配方默认总是执行)。正如 README 所述,just 会在运行前静态解析错误:未知配方、循环依赖在真正执行任何命令之前就被报告出来。

以下核心事实均可在仓库中找到依据:

  • 错误信息明确且具体:语法错误会连同源码上下文一并报告。例如 src/compile_error_kind.rs 中定义了 CircularRecipeDependency、CircularVariableDependency 等编译错误类型,src/compile_error.rs 会输出形如 recipe `foo` has circular dependency `foo -> bar -> foo` 的可读信息。
  • 跨平台:支持 Rust 所支持的全部操作系统(Linux、macOS、Windows 及其他类 Unix 系统),且无需额外依赖。
  • 静态检查优先:在 src/compiler.rs 中,编译阶段就会对循环导入、未知配方等错误做静态校验,而非等到运行时才暴露。

安装 just

just 的安装途径非常丰富,仓库根目录的 justfile 中甚至专门定义了 install 配方(cargo install -f just)。以下是主要方式:

用包管理器安装

just 已进入几乎所有主流平台的包管理器,常见的安装命令包括:

平台 包管理器 命令
跨平台 Cargo(crates.io) cargo install just
跨平台 Cargo Binstall cargo binstall just
跨平台 Homebrew brew install just
跨平台 Conda conda install -c conda-forge just
跨平台 Nix nix-env -iA nixpkgs.just
跨平台 npm npm install -g rust-just
跨平台 pipx pipx install rust-just
跨平台 uv uv tool install rust-just
跨平台 Snap snap install --edge --classic just
Linux (Debian 13/Ubuntu 24.04+) apt apt install just
Linux (Arch) pacman pacman -S just
Linux (Fedora) DNF dnf install just
Linux (Alpine) apk apk add just
Linux (openSUSE) Zypper zypper in just
Linux (Void) XBPS xbps-install -S just
Linux (Gentoo) Portage emerge -av dev-build/just
Linux (NixOS) Nix nix-env -iA nixos.just
macOS MacPorts port install just
Windows Chocolatey choco install just
Windows Scoop scoop install just
Windows Windows Package Manager winget install --id Casey.Just --exact
BSD (FreeBSD) pkg pkg install just
BSD (OpenBSD) pkg_add pkg_add just

使用预编译二进制

Linux、macOS、Windows 的预编译二进制发布在 GitHub Releases,可用仓库自带的一键安装脚本安装,把 DEST 替换为目标目录即可:

curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to DEST

例如安装到 ~/bin 并加入 PATH:

mkdir -p ~/bin
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to ~/bin
export PATH="$PATH:$HOME/bin"
just --help

该脚本(仓库内对应 www/install.sh)通过 GitHub API 查询最新版本,按 IP 限流;在 GitHub Actions 等共享 IP 环境下可能失败,此时可指定 --tag 安装特定版本,或设置环境变量 GITHUB_TOKEN 进行认证。

从源码构建

克隆仓库后执行 cargo install --path .,或直接 cargo install just 从 crates.io 安装最新发布版。仓库的 Cargo.toml 定义了完整的 crate 元数据与依赖。

Docker 与 Nix Flake

just 发布了官方容器镜像,可在 Dockerfile 中直接复制二进制:

COPY --from=ghcr.io/casey/just:latest /just /usr/local/bin/

之后就能在构建过程中使用 RUN just。仓库根目录的 flake.nix 定义了 Nix Flake,可将 just 作为另一个 flake 的输入:

{
  inputs = {
    just.url = "github:casey/just";
  }
  outputs = {self, nixpkgs, just}: {
  }
}

快速上手:第一个 justfile

安装完成后用 just --version 验证。然后在项目根目录创建 justfile:

recipe-name:
  echo 'This is a recipe!'

# this is a comment
another-recipe:
  @echo 'This is another recipe.'

关键行为与 src/search.rs 中的实现一一对应:

  • 查找规则:just 会在当前目录及其向上各级目录中查找 justfile,因此你可以在项目的任意子目录中调用它。查找不区分大小写,Justfile、JUSTFILE、JuStFiLe 均可;也会识别隐藏文件 .justfile。
  • 默认配方:不带参数运行 just 会执行第一个配方(若有 [default] 属性的配方则执行该配方):
$ just
echo 'This is a recipe!'
This is a recipe!
  • 指定配方:参数即配方名,可一次指定多个(无依赖的配方按命令行给出的顺序执行):
$ just another-recipe
This is another recipe.
  • 回显规则:just 会在执行前把每条命令打印到标准错误;以 @ 开头的行不打印。这就是上面 echo 'This is a recipe!' 被打印、而 @echo 那行没有打印的原因。
  • 失败即停:配方中任何一条命令失败,后续命令不再执行。例如下面的 publish 只在 cargo test 成功后才执行 cargo publish:
publish:
  cargo test
  # tests passed, time to publish!
  cargo publish

配方(Recipes)详解

默认配方

[default] 属性可显式指定默认配方;未标注时取第一个配方。默认配方适合放最常用的命令,比如测试:

test:
  cargo test

也可用依赖把多个配方串成默认流程:

default: lint build test

build:
  echo Building…

test:
  echo Testing…

lint:
  echo Linting…

如果没有任何配方适合作为默认配方,可以设置 set default-list := true,让无参数运行时改为列出所有可用配方。

配方参数

配方可以接收命令行参数,参数在 {{...}} 中插值:

build target:
  @echo 'Building {{target}}…'
  cd {{target}} && make
$ just build my-awesome-project
Building my-awesome-project…
cd my-awesome-project && make

参数的进阶能力非常丰富(README 的 Recipe Parameters 一节有完整说明):

  • 依赖传参:把依赖连同参数写在括号里,default: (build "main");变量、上层配方的参数都可以这样透传。
  • 默认值:test target tests=default:,有默认值的参数可以省略,默认值可以是任意表达式,但含 +、&&、||、/ 运算符的表达式必须加括号。
  • 可变参数:+ 前缀表示"一个或多个",* 前缀表示"零个或多个",展开为空格分隔的字符串;可变参数也可有默认值。可用 [arg(ARG, min=MIN, max=MAX)] 属性限制个数(需启用 set lists)。
  • 正则约束:[arg('n', pattern='\d+')] 可限制参数匹配正则,模式值本身也允许是 const 表达式。
  • 环境变量导出:以 $ 前缀的参数字段会自动导出为环境变量,如 foo $bar:。
  • 用法输出:just --usage foo 可打印配方的参数用法;[arg(ARG, help=HELP)] 可为参数添加帮助文本。

配方旗标与选项

参数默认是位置式的,但可用 [arg] 属性把它们变成选项:

[arg("bar", long="bar")]
foo bar:

之后可用 just foo --bar hello 或 just foo --bar=hello 传值。long 缺省时取参数名;short="b" 则启用 -b 短选项(缺省时取参数首字母)。多个短选项可组合(-abc 等价于 -a -b -c)。若给选项提供固定 value,则该选项变成"开关型旗标",例如强制 --force 类旗标:

[arg("bar", long="bar", value="hello")]
foo bar:
$ just foo --bar
bar=hello

参数有默认值时旗标成为可选项。

依赖(Dependencies)

依赖在依赖它的配方之前运行(称为 prior dependencies):

build:
  cc main.c foo.c bar.c -o main

test: build
  ./test
$ just test
cc main.c foo.c bar.c -o main
./test
testing… all tests passed!

同一参数在单次调用中只运行一次(去重),无论它出现在命令行几次或被几个配方依赖:

$ just a a a a a
A
$ just b c
A
B
C

依赖也可以后置:用 && 引入的 subsequent dependencies 在配方自身执行完之后运行:

b: a && c d

若想在配方中间调用另一个配方,just 本身不支持"中置依赖",但可以在配方体内递归调用 just c。注意这会启动全新的 just 进程,赋值会重新计算、依赖可能运行两次、命令行参数也不会传给子进程。

依赖还可以并行执行:给配方加 [parallel] 属性,其依赖(如 main: foo bar baz)会并发运行;--jobs 选项(1.56.0 起)可限制并发数。

参数避免被 shell 拆分

{{argument}} 插值不会保留引号,just foo "some argument.txt" 会被展开成 touch some argument.txt 从而创建两个文件。三种规避方案:

  1. 引号包裹:touch '{{argument}}'(保留变量名拼写检查,但值含单引号时不生效);
  2. 位置参数:set positional-arguments 后参数以 $1、$2、$@ 暴露,配合 "$@" 双引号防止二次拆分(此方案对所有值都有效,但失去拼写检查);
  3. 导出参数:set export 导出全部参数,或以 $ 前缀导出单个参数,再通过 "$argument" 引用。

positional-arguments 也可以按配方启用([positional-arguments] 属性)。注意 PowerShell 对位置参数的处理与其他 shell 不同,启用后可能破坏使用 PowerShell 的配方;PowerShell 7.4+ 可用 -CommandWithArgs 旗标配合 set shell := ['pwsh.exe', '-CommandWithArgs'] 获得符合预期的行为。

文档注释、分组、别名与私有配方

  • 紧邻配方上方的注释会出现在 just --list 中;[doc('...')] 可覆盖或(空参数)隐藏注释。
  • [group('lint')] 属性可给配方分组,just --list 按组展示,--groups 列出所有组,--list --unsorted 保持 justfile 内的书写顺序。
  • 别名让配方拥有额外调用名:alias b := build;别名目标也可以是子模块配方(foo::bar)或整个模块(1.55.0 起)。
  • 以下划线开头的配方/别名不会出现在 just --list 与 just --summary 中;[private] 属性(1.10.0 起)可在不改名的情况下隐藏配方,适合仅作为依赖使用的辅助配方。

操作系统条件属性

[unix]、[windows]、[linux]、[macos]、[freebsd] 等条件属性(1.56.0 起可作用于所有顶层条目)能按操作系统切换行为,例如不同系统用不同编译器:

[unix]
run:
  cc main.c
  ./a.out

[windows]
run:
  cl main.c
  main.exe

设置项同样可以条件化:[unix] set shell := ['sh', '-cu']。allow-duplicate-recipes 开启后同名配方不再报错,以最后一个定义为准(默认关闭)。

表达式与内置函数

模块级变量用 := 定义,支持字符串、列表、条件表达式与丰富的内置函数:

foo := "hello"
bar := "world"

baz:
  echo {{ foo + " " + bar }}

just --evaluate 可打印模块全部变量,just --evaluate foo 打印单个变量值。内置函数覆盖字符串处理(trim、replace、quote)、路径操作(absolute_path、parent_directory、extension、clean、join)、系统信息(os()、os_family()、arch()、num_cpus())、环境变量(env_var、env_var_or_default)、文件系统(path_exists、sha256_file)等数十种——examples/kitchen-sink.just 一口气演示了绝大多数函数与语法特性,是绝佳的速查素材。README 中 Expressions 一节对这些函数有完整索引。

just 还支持从 .env 文件加载环境变量(set dotenv-load 或 --dotenv 选项),配合 export 设置把变量导出给配方内的命令,方便集成现有环境配置。

跨平台:换 shell 与 shebang 脚本

just 在无 sh 的 Windows 上同样可用。默认它依赖 sh(Windows 上可用 Git for Windows、GitHub Desktop 或 Cygwin 提供的 sh),你也可以用 shell 设置显式选择:

# use PowerShell instead of sh:
set shell := ["powershell.exe", "-c"]

hello:
  Write-Host "Hello, world!"
# use cmd.exe instead of sh:
set shell := ["cmd.exe", "/c"]

list:
  dir

也可通过命令行参数切换:just --shell powershell.exe --shell-arg -c。Windows 场景下 PowerShell 是多数用户的首选(cmd.exe 细节较繁琐)。

配方还可以写成 shebang 脚本,用任意语言实现,just 会把配方整个写入临时文件执行:

_python:
  #!/usr/bin/env python3
  print('Hello from python!')

仓库根目录 justfile 中的 polyglot 配方甚至用 Python、JavaScript、Perl、shell、nushell、Ruby 六种语言各写了一个 hello 配方,演示了 shebang 配方的跨语言能力。README 的 Shebang Recipes 一节还说明 shebang 行支持 set shell 展开、可结合 --shell 解析等细节。

模块与导入:组织大型 justfile

justfile 可以用模块(module)组织成多文件,配方可跨模块引用:

mod foo

baz: foo::bar
alias baz := foo::bar

模块文件与模块同名(如 foo.just),README 的 Modules 与 Imports 两节给出了完整的模块声明、私有模块(mod foo 前加 [private])、模块分组([group('...')])以及 just --list 按模块展示等能力。这为大型项目的配方治理提供了类似"命名空间"的机制。

编辑器支持与命令行补全

justfile 语法与 make 足够接近,多数编辑器可直接套用 make 高亮:

  • Vim/Neovim:Vim 9.1.1042+ 与 Neovim 0.11+ 原生支持;也可安装 vim-just 插件或用 tree-sitter-just;
  • Emacs:just-mode(MELPA)提供高亮与自动缩进,justl 提供执行/列配方命令;文件尾部加 # mode: makefile 可单文件启用 make 模式;
  • VS Code / JetBrains / Zed:分别有 vscode-just 扩展、JetBrains 插件与 zed-just 扩展;
  • Kakoune、Helix、Sublime Text、Micro 均开箱支持或提供语法包。

命令行补全脚本仓库内直接提供,见 completions 目录(bash、elvish、fish、nu、powershell、zsh),just --completions SHELL 也可动态生成。集成 CI(如 GitHub Actions)时可用 extractions/setup-just 或 taiki-e/install-action 安装指定版本,README 的 GitHub Actions 一节给出了完整 YAML 示例。

向后兼容与最低版本约束

just 1.0 起承诺强向后兼容:未来版本不会引入破坏既有 justfile 或 CLI 调用的不兼容变更,且永远不会出现 just 2.0——任何需要破坏性变更的功能将以"每 justfile 可选项"的形式提供。尚未稳定的特性标记为 unstable,默认使用会报错,可用 --unstable 旗标、set unstable 或环境变量 JUST_UNSTABLE(非 false/0/空串的值)开启。

如果你的 justfile 用到了特定版本才有的特性,可在文件顶部声明最低版本要求,让旧版 just 直接给出明确提示而非莫名其妙的解析错误:

set minimum-version := '1.55.0'

注意该检查由解析器实现、在词法分析之后执行,因此词法层面向前不兼容的特性仍可能产生晦涩错误;minimum-version 应置于 justfile 顶部、任何受保护新特性之前。

实战:一份完整的跨平台 justfile

结合以上全部能力,参考 examples/cross-platform.just 与仓库自用的根 justfile,一份典型的项目 justfile 大致长这样:

set dotenv-load
set export

python_dir := if os_family() == "windows" { "./.venv/Scripts" } else { "./.venv/bin" }
python := python_dir + if os_family() == "windows" { "/python.exe" } else { "/python3" }

# 设置开发环境
[group('setup')]
bootstrap:
    {{ python }} -m pip install --upgrade pip
    {{ python }} -m pip install -r requirements.txt

# 运行测试
[group('test')]
test: bootstrap
    {{ python }} -m pytest

# 支持透传参数的脚本
[group('dev')]
run *ARGS:
    {{ python }} app.py {{ ARGS }}

# 用 PowerShell 作为 Windows 默认 shell 的示例(shebang 配方)
[windows]
debug:
    #!{{ if os() == 'windows' { 'powershell.exe' } else { '/usr/bin/env pwsh' } }}
    Write-Host "debug session"

这份配方同时运用了变量与条件表达式、分组、依赖、可变参数、shebang 脚本与条件属性——也正是在 etc/crates-io-readme.md 那短短几行示例之上,just 能为项目带来的完整价值。更系统的语法参考可以继续阅读仓库内 README.md(含全部特性索引)与 examples 目录下的多种真实场景示例。

登录后查看全文
just