Justfile 速查清单:just 命令运行器的配方编写、变量系统与命令行实战指南
Justfile 速查清单:just 命令运行器的配方编写、变量系统与命令行实战指南
本篇技术指南以 docs/justfile.md 备忘清单为骨架,系统讲解 just 这一项目特有命令运行器的完整用法:从最基础的配方(recipe)编写、参数与变量传递,到 backtick 输出捕获、依赖编排、条件表达式、环境变量注入,以及 just --list、just --show 等命令行操作。读完本文,你将能够在自己的项目中快速落地一份可维护、可复用、支持自定义 shell 与 .env 加载的 justfile,并理解 just 与 Make 类工具在"每个命令行由新 shell 执行、失败即退出"上的关键行为差异。
本文所属仓库 jaywcjlove/reference 是一份面向开发者的快速参考备忘清单合集,justfile 速查表是其中的一份独立文档,适合在编写 or 审阅 justfile 时随时查阅。
一、入门:第一份 justfile 配方
just 提供了一种保存和运行项目特有命令的便捷方式。它的核心概念是配方(recipe):一个带名字的命令序列,类似 Makefile 中的 target,但语法更简洁、行为更贴近直觉。
一份最简单的 justfile 只需要一个配方名加一行命令:
#!/usr/bin/env just --justfile
# hello 是配方(recipe)的名字
hello:
echo "Hello World!"
保存为 justfile 后,在项目根目录执行 just hello 即可运行。需要注意两点:
- 配方体(recipe body)中的命令必须以制表符或空格缩进,
just要求配方体与配方名行有明确的缩进区分; - 行首的
#!/usr/bin/env just --justfile不是必需的,但加上它可以让 justfile 本身具备"可执行脚本"语义(配合chmod +x justfile后可直接运行),也方便编辑器识别语法。
在 justfile 内注释与组织
- 以
#开头的行是注释,just --list会读取配方上方的注释作为该配方的说明文字; - 配方顺序即文件中定义的顺序,没有显式默认配方时,第一个配方会被当作默认配方(详见下文"默认配置"小节)。
二、带参数的配方:默认值、表达式与可变参数
just 的配方支持参数,这是它相比简单别名脚本的核心优势之一。
filter PATTERN:
echo {{PATTERN}}
配方体中使用 {{PATTERN}} 插值引用参数。调用方式为 just filter "*.rs",位置参数按定义顺序传入。
带默认值的参数
# 带有默认值的 param
email address='master@example.com':
echo {{address}}
参数通过 name='default' 语法声明默认值。不传该参数时使用默认值,just email 与 just email foo@bar.com 均合法。
带表达式的参数
# 带表达式的参数
test triple=(arch() + "-unknown-unknown"):
./test {{triple}}
默认值不仅可以是一个字面量,还可以是表达式。这里用内置函数 arch() 拼出目标三元组(triple),例如在 x86_64 机器上解析为 x86_64-unknown-unknown。表达式在每次调用时求值,因此可以动态生成参数。
可变参数:+ 与 *
# 变量参数:"+"接受一个或多个值
backup +FILES:
scp {{FILES}} me@example.com
# 带*的可变参数:零个或多个值
commit MESSAGE *FLAGS:
git commit {{FLAGS}} -m "{{MESSAGE}}"
+FILES:一个或多个值,至少传一个,just backup a.txt b.txt;*FLAGS:零个或多个值,可以不传,just commit "fix bug" -a --no-verify。
可变参数会以空格分隔展开到 {{...}} 插值处,非常适合透传文件列表或命令选项。
三、变量与子变量:justfile 的常量系统
justfile 支持在顶层定义变量,使用 := 赋值,这与配方参数的 = 默认值语法相区分(:= 定义的是文件级变量,不是参数默认值):
version := "0.2.7"
tardir := "awesomesauce-" + version
tarball := tardir + ".tar.gz"
test:
echo {{version}}
关键点:
- 变量支持字符串拼接,
tardir是version的"子变量",tarball又基于tardir,形成可推导的派生链; - 变量在配方中用
{{...}}插值; - 变量在 justfile 被解析时即求值(除非使用 backtick 延迟求值,见后文)。
从命令行覆盖变量:--set
# 仅从命令行设置/覆盖变量
$ just --set version 1.1.0
just --set NAME VALUE 可以在不修改 justfile 文件的前提下临时覆盖变量值,适合 CI 或环境切换场景。该语法只对变量(:=)生效,不能用来覆盖配方参数。
四、默认配置:default 配方与自动帮助
default: lint build test
# 显示帮助信息的默认配方
default:
@just --list
# 如果没有默认配方,则默认第一个配方
- 可以声明一个名为
default的配方作为入口。上方第一个示例中default: lint build test通过依赖语法(见"配置依赖性"一节)串联多个配方,直接执行just即可依次运行lint、build、test; - 第二个示例中,
default配方体内执行@just --list(@前缀抑制命令回显),这样裸执行just时直接展示全部配方清单,相当于内置帮助页; - 如果没有
default配方,just会默认执行文件中定义的第一个配方,因此把最常用的配方放在最顶部是一种常见组织习惯。
五、命令的环境变量:export 与配方级注入
全局导出
export RUST_BACKTRACE := "1"
test:
# 如果堆栈崩溃,将打印堆栈跟踪
cargo test
顶层 export NAME := value 会把变量注入到每个配方命令的进程环境中。上面的例子对所有配方导出 RUST_BACKTRACE=1,一旦 cargo test 崩溃即可打印完整堆栈。
配方参数作为环境变量:$name
# recipe 参数作为$符号的Env变量
hello $name:
echo $name
参数名以 $ 前缀声明时,该参数会直接作为环境变量传入配方体,配方内用 $name 而不是 {{name}} 引用。这一机制在处理"命令内部再调用子进程并需要环境透传"的场景时更自然,也避免了插值带来的引号转义问题。
六、backtick:从命令输出中捕获值
just 的 backtick(反引号)语法可以执行外部命令并把标准输出捕获为值,这是它动态化程度最高的特性之一:
JAVA_HOME := `jbang jdk home 11`
# Backtick 代码块
stuff := \```
foo="hello"
echo $foo "world"
\```
done BRANCH=`git rev-parse --abbrev-ref HEAD`:
git checkout master
sloc:
@echo "`wc -l *.c` lines of code"
# Backtick 在任何地方工作:字符串/变量/参数
- 变量:
JAVA_HOME := \jbang jdk home 11`` 在解析时执行命令并捕获输出(这里是获取 JDK 11 的安装路径); - 多行 backtick 代码块:用转义的三反引号
\``...```包裹,可执行多行 shell 逻辑后把整体输出作为值(示例中stuff的值为hello world`); - 配方参数默认值:
done BRANCH=\git rev-parse --abbrev-ref HEAD`` 把当前分支名作为参数默认值,动态又稳妥; - 配方体内:
@echo "`wc -l *.c` lines of code"在命令替换语境下使用。
注意:原文档指出,上面示例中用于标识代码块的 \` 在实际 justfile 中不需要转义,速查表里是为了在 Markdown 中展示才加了反斜杠。
七、别名与字符串转义
别名
alias t := test
alias c := check
alias 短名 := 配方名 为配方定义别名,方便输入。别名同样会出现在 just --list 中,且可以被依赖语法引用。
字符串转义规则
tring-with-tab := "\t"
string-with-newline := "\n"
escapes := '\t\n\r\"\\'
# 该字符串将评估为`foo\nbar\n`
x := '''
foo
bar
'''
- 双引号字符串中
\t、\n等转义序列会被解析为真实字符; - 单引号字符串中
\t\n\r\"\\保持字面量含义(escapes的实际值就是反斜杠加字母); - 三单引号
'''...'''是多行字符串,内容保留换行,且行首缩进会被剥离——示例中x求值为foo\nbar\n。
八、配方体控制:quiet(@)、ignore(-)、invert(!)
just 为每一条配方体命令行提供了三个前缀修饰符:
hello:
@ echo "command will not be echoed"
- echo "ignore none-zero exit status and continue"
@hello2:
echo "command will not be echoed"
# 反转命令退出状态!- shell 功能
hello3:
# 如果命令成功(退出状态为0),请仅退出
! git branch | grep '* master'
@(quiet):不回显该命令。可以加在单条命令前(@ echo ...),也可以加在配方名前(@hello2:)让整个配方体的命令都不回显;-(ignore):忽略该命令的非零退出码,失败后继续执行后续命令,用于清理类或"尽力而为"的命令;!(invert):反转命令的退出状态,依赖 shell 的取反语义——示例中git branch | grep '* master'在处于 master 分支时成功,!反转后该命令以失败状态结束,配合 just"失败即退出"的默认行为,实现"仅当不在 master 分支时才继续"的守卫逻辑。
九、设置项:shell、dotenv 与位置参数
set 指令用于调整 just 的运行时行为:
set shell := ["zsh", "-cu"]
set dotenv-load := true
serv:
echo "$DATABASE_ADDRESS from .env"
set positional-arguments := true
foo:
echo $0
echo $1
set shell := ["zsh", "-cu"]:指定执行配方命令的 shell 及参数(默认是["sh", "-cu"])。改成zsh、bash后即可使用对应 shell 的语法特性(如数组、[[ ]]等);set dotenv-load := true:启动时加载项目根目录的.env文件,把其中变量注入环境。示例配方中的$DATABASE_ADDRESS就来自.env;set positional-arguments := true:把调用 just 时配方名之后的额外参数作为位置参数暴露给配方体,配方内通过$0、$1等读取(此时 just 本身作为脚本解释器使用)。注意此模式下参数不再绑定配方形参,而是按位置原样透传。
十、配置依赖性:之前、之后与周围
just 支持三种依赖编排方式:
# 执行序列:A-> B-> C-> D
b: a && c d
# 执行配方(recipe)"A"
b:
echo 'B start!'
just a
echo 'B end!'
# 通过表达式依赖参数
default: (build "main")
build target:
@echo 'Building {{target}}...'
- 顺序依赖(依赖列表):
b: a && c d表示执行b前先依次执行a、c、d(&&表示其后的依赖与前一组并行执行,c和d会并发运行;不写&&则是严格串行)。这是"之前"的编排; - 配方内调用(周围):在
b的配方体里显式执行just a,从而控制a在b的中间位置运行——输出顺序为B start!→ 执行a→B end!; - 带参数的依赖:
default: (build "main")允许在依赖声明中给配方传入参数,build target将收到main作为target的值。这是 Make 风格依赖无法直接做到的。
十一、Just 内置函数
just 提供了一组内置函数,可在变量定义、参数默认值和配方体插值中使用:
hello name:
echo {{os()}}
echo {{uppercase(name)}}
示例中 os() 返回当前操作系统名称(如 linux、macos),uppercase(name) 把参数转为大写。函数类别主要包括:
- 系统信息:
os()、arch()、num_cpus()等; - Justfile 与 Justfile 目录:
justfile()、justfile_directory()、source_file()等路径类函数; - 字符串操纵:
uppercase()、lowercase()、replace()、trim()、split()、capitalize()等; - 路径操纵:
join()、parent_directory()、file_name()、extension()等; - 其他:
env_var()、env_var_or_default()等环境读取函数,以及assert()等校验函数。
# String contact: (key + ":" + value)
函数同样可以参与表达式运算,例如用 key + ":" + value 拼接出键值对字符串。函数清单在不同版本中会持续扩充,编写前可先运行 just --help 或查阅 just 官方文档确认当前版本可用函数。
十二、条件表达式:if、loop 与 while
just 的变量和插值支持 if 表达式,配方体命令则由所选 shell 提供循环能力:
# 正则表达匹配
fo := if "hi" =~ 'h.+' { "match" } else { "mismatch" }
test:
if true; then echo 'True!'; fi
for file in `ls .`; do echo $file; done
while `server-is-dead`; do ping -c 1 server; done
foo bar:
echo {{ if bar == "bar" { "hello" } else { "bye" } }}
- 变量级 if 表达式:
if 条件 { 值 } else { 值 },条件支持=~正则匹配('h.+'匹配hi),也支持==、!=、比较运算符与逻辑组合; - 配方体内插值 if:
{{ if bar == "bar" { "hello" } else { "bye" } }}根据参数值在插值时选择输出; - shell 循环:
if/then/fi、for ... in ...、while ...都是普通 shell 命令,直接写在配方体内即可,例如用for file in \ls .`遍历文件、用while` 轮询服务器状态。
十三、Just 命令行:运行、列举、展示与补全
# 运行配方(recipe)
$ just hello param1
# 按字母顺序列出配方(recipe)
$ just --list
$ just --summary
# 显示有关配方(recipe)的完整信息
just --show test
# 选择以交互方式运行的配方(recipe)
$ just --choose
# shell 完成
just --completions zsh
just hello param1:运行hello配方并传入param1;just --list:按字母顺序列出所有配方(含注释说明与参数签名);just --summary只输出配方名,便于脚本消费;just --show test:打印test配方的完整定义(依赖与配方体),是排查问题时最常用的只读命令;just --choose:进入交互式选择器,用方向键挑选要执行的配方;just --completions zsh:为指定 shell(zsh、bash、fish、powershell 等)输出补全脚本,把输出重定向到 shell 的补全目录即可启用 TAB 补全。
十四、特殊技巧:多语言配方、私有配方与注意事项
用 shebang 编写其他语言的配方
bash-test:
#!/usr/bin/env bash
set -euxo pipefail
hello='Yo'
echo "$hello from bash!"
在配方体内使用 shebang 行,即可让该配方以指定解释器执行,从而使用 bash 的 set -euxo pipefail、数组等特性——即使全局 set shell 还是默认的 sh。
私有配方:以下划线开头
test: _test-helper
./bin/test
# ommited from 'just --list'
_test-helper:
./bin/super-secret-test-helper-stuff
名称以 _ 开头的配方会被视为私有配方:不会出现在 just --list 中,但仍可被其他配方依赖调用。适合隐藏内部辅助逻辑,保持帮助清单整洁。
需要牢记的行为特性
# 每个命令行都由一个新的 shell 执行
# 如果一个命令行执行失败,just会退出
# 后面的命令行不会执行
change-working-dir:
cd bar && pwd
# 多行构造 - 用斜线转义换行符
if true; then \
echo 'True!'; \
fi
# justfile 不区分大小写:Justfile、JUSTFILE 等
# justfile 可以被隐藏:'.justfile'
# 从子目录调用配方:`~/app1/target>$ just build`
- 每行一个新 shell:just 的配方体中每一行命令都由一个新的 shell 进程执行,因此
cd bar只影响本行,想改变后续命令的工作目录必须写成cd bar && pwd; - 失败即退出:某条命令返回非零退出码时,just 立即退出,后续命令行不会执行(除非该命令带
-前缀或!反转); - 多行构造:shell 的多行语法(如
if ... then)需要跨行时,用行尾反斜杠\转义换行符,让 just 把它们拼成同一条命令; - 文件名与位置:justfile 文件名不区分大小写(
justfile、Justfile、JUSTFILE均可);文件可以隐藏为.justfile(此时需用-f显式指定);从子目录运行时,just 会向上查找 justfile,因此~/app1/target下直接执行just build也能找到项目根目录的 justfile。
把 just 配方导出为 shell 别名
for recipe in `just -f ~/.justfile --summary`; do
alias $recipe="just -f ~/.justfile -d. $recipe"
done
把这段脚本放进 shell 的启动文件(如 .bashrc、.zshrc),即可把 ~/.justfile(个人全局 justfile)中所有配方注册成 shell 别名,实现"任何目录下直接输入配方名即可运行"。-d. 表示以当前目录作为 justfile 的查找起点,保证别名在任意工作目录生效。
十五、IDE 集成
just 社区提供了主流编辑器的语法与运行支持:
- VS Code:安装 Just 扩展(市场内搜索
just相关扩展)可获得语法高亮、配方跳转与一键运行; - JetBrains 系(IntelliJ IDEA、PyCharm、GoLand 等):安装 Just 插件后支持 justfile 语法高亮与运行配置。
安装后打开项目中的 justfile 即可生效,与本文介绍的语法完全一致。
十六、小结与速查对照
| 关注点 | 语法要点 |
|---|---|
| 配方 | name: + 缩进命令体 |
| 参数 | name arg: 配合 {{arg}} 插值 |
| 默认值 | name arg='val':、arg=(expr) |
| 可变参数 | +FILES(≥1)、*FLAGS(≥0) |
| 文件级变量 | var := "value",命令行 just --set var val 覆盖 |
| 环境注入 | 顶层 export V := "1";参数 $name 直接作为环境变量 |
| 动态值 | v := `cmd`、多行反引号块、参数默认值反引号 |
| 依赖编排 | b: a、b: a && c d(并行)、配方内 just a、(build "arg") |
| 命令修饰 | @ 静默、- 忽略错误、! 反转退出码 |
| 设置项 | set shell、set dotenv-load、set positional-arguments |
| 条件与函数 | {{ if ... {..} else {..} }}、os()、uppercase() 等内置函数 |
| 命令行 | just --list/--summary/--show/--choose/--completions |
just 以接近脚本的语法提供了远超 Make 的灵活性与可读性,是管理项目任务链、构建步骤与开发辅助命令的轻量方案。将本文作为速查手册,配合 just --list 与 just --show 两个自省命令,即可在真实项目中快速排查配方定义、验证依赖顺序,并逐步把重复的手工命令收敛进项目自己的 justfile 中。