Justfile 速查清单:just 命令运行器的配方编写、变量系统与命令行实战指南

原创2026-09-22 10:50:341,853 阅读
文章标签:文档教程知识库

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}}...'
  1. 顺序依赖(依赖列表):b: a && c d 表示执行 b 前先依次执行 a、c、d(&& 表示其后的依赖与前一组并行执行,c 和 d 会并发运行;不写 && 则是严格串行)。这是"之前"的编排;
  2. 配方内调用(周围):在 b 的配方体里显式执行 just a,从而控制 a 在 b 的中间位置运行——输出顺序为 B start! → 执行 a → B end!;
  3. 带参数的依赖: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 中。

登录后查看全文
reference