just 命令运行器实战指南:用 justfile 保存并运行项目专属命令
just 命令运行器实战指南:用 justfile 保存并运行项目专属命令
just 是一款用 Rust 编写的命令行运行器(command runner),它以 make 为灵感、却规避了 make 的大量怪癖,让你把项目特有的命令以"配方(recipe)"的形式保存在 justfile 中,随时一键调用。本指南以 etc/crates-io-readme.md 为核心骨架,结合仓库源码与 README.md、examples 目录下的真实示例,系统讲解从安装、快速上手到配方参数、依赖、跨平台脚本、模块组织的完整方案,读完你就能为自己的项目写出一份专业、可维护的 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 从而创建两个文件。三种规避方案:
- 引号包裹:
touch '{{argument}}'(保留变量名拼写检查,但值含单引号时不生效); - 位置参数:
set positional-arguments后参数以$1、$2、$@暴露,配合"$@"双引号防止二次拆分(此方案对所有值都有效,但失去拼写检查); - 导出参数:
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 目录下的多种真实场景示例。
