Justfile

Justfile 命令自动化技能

将常用命令、Makefile、npm scripts 转换为 Justfile，便于日常开发和运维工作。

快速开始

安装 just

# macOS
brew install just

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash

# 验证安装
just --version

基本使用

just              # 运行默认 recipe
just --list       # 列出所有 recipes
just <recipe>     # 运行指定 recipe
just -n <recipe>  # 干运行（只显示命令）

工作流程决策

根据用户需求选择合适的工作流程：

用户需求
├── 已有 Makefile → 转换工作流
├── 已有 package.json → npm 转换工作流
├── 有常用 shell 命令 → 命令整理工作流
├── 新项目需要自动化 → 模板生成工作流
└── 需要了解语法 → 查阅 references/syntax.md

1. Makefile 转换

将现有 Makefile 转换为 Justfile。

自动转换

python scripts/makefile_to_just.py Makefile justfile

手动转换要点

• 移除 .PHONY 声明（just 默认都是 phony）
• $(VAR) → {{var}}
• $(shell cmd) → `cmd`
• 保持 @ 前缀（静默执行）
• 文件依赖需要移除或改为 recipe 依赖

转换示例

# Makefile
.PHONY: build test
VERSION := $(shell git describe --tags)

build:
	go build -ldflags "-X main.version=$(VERSION)"

test: build
	go test ./...

转换为：

# justfile
version := `git describe --tags`

build:
    go build -ldflags "-X main.version={{version}}"

test: build
    go test ./...

2. npm scripts 转换

将 package.json 中的 scripts 转换为 Justfile。

自动转换

python scripts/npm_to_just.py package.json justfile

转换示例

{
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "test": "vitest",
    "lint": "eslint ."
  }
}

转换为：

set dotenv-load

default: dev

dev:
    npm run dev

build:
    npm run build

test:
    npm run test

lint:
    npm run lint

# 或者直接使用原始命令
dev:
    vite

build:
    vite build

3. Shell 命令整理

将常用 shell 命令整理为 Justfile。

从 history 提取

python scripts/shell_to_just.py --history justfile

从文件读取

# 创建命令列表
cat > commands.txt << 'EOF'
docker-compose up -d
docker-compose logs -f
kubectl get pods -n production
kubectl logs -f deployment/api
EOF

python scripts/shell_to_just.py commands.txt justfile

手动整理模式

收集用户常用命令，按功能分组：

# === Docker ===
up:
    docker-compose up -d

down:
    docker-compose down

logs service="":
    docker-compose logs -f {{service}}

# === Kubernetes ===
pods:
    kubectl get pods -n production

logs-k8s pod:
    kubectl logs -f {{pod}} -n production

4. 项目模板生成

根据项目类型生成合适的 Justfile 模板。

识别项目类型

检查项目文件来识别类型：

生成模板

查阅 references/templates.md 获取各类项目的完整模板：

• Python 项目模板
• Node.js 项目模板
• Go 项目模板
• DevOps/运维模板
• 通用开发模板
• 数据科学/ML 模板

常用 Recipe 模式

带参数的 Recipe

# 必需参数
deploy env:
    kubectl apply -k overlays/{{env}}

# 默认值参数
build mode="debug":
    cargo build --{{mode}}

# 可变参数
test *args:
    pytest {{args}}

依赖关系

# 简单依赖
release: build test
    ./deploy.sh

# 带参数的依赖
push: (build "release")
    docker push myapp:latest

条件执行

# 跨平台
[linux]
install:
    apt install mypackage

[macos]
install:
    brew install mypackage

# 确认提示
[confirm("确定要部署到生产环境吗?")]
deploy-prod:
    kubectl apply -k overlays/prod

分组

[group('development')]
dev:
    npm run dev

[group('development')]
watch:
    npm run watch

[group('testing')]
test:
    npm run test

脚本模式

[script]
setup:
    #!/usr/bin/env bash
    set -euo pipefail

    echo "Setting up environment..."
    for pkg in curl git make; do
        command -v $pkg || echo "Missing: $pkg"
    done

最佳实践

1. 文件组织

# 头部：设置和变量
set dotenv-load
set shell := ["bash", "-cu"]

project := "myapp"
version := `git describe --tags --always`

# 默认 recipe
default: dev

# 按功能分组，用注释分隔
# === 开发 ===
dev: ...

# === 构建 ===
build: ...

# === 测试 ===
test: ...

2. 命名约定

• 使用小写字母和连字符：build-prod
• 动词开头：run, build, test, deploy
• 私有 recipe 用下划线：_helper

3. 文档注释

# 启动开发服务器 (端口 3000)
dev:
    npm run dev

4. 变量使用

# 从环境变量读取，带默认值
env := env("ENV", "development")

# 从命令获取
commit := `git rev-parse --short HEAD`

# 条件变量
mode := if env == "prod" { "release" } else { "debug" }

参考资料

• references/syntax.md - Justfile 完整语法参考
• references/templates.md - 各类项目模板集合
• scripts/makefile_to_just.py - Makefile 转换脚本
• scripts/npm_to_just.py - npm scripts 转换脚本
• scripts/shell_to_just.py - Shell 命令提取脚本