mise run 命令完全指南：任务调度、新鲜度检查、缓存与沙箱执行-平芜编程栈

mise run 命令完全指南：任务调度、新鲜度检查、缓存与沙箱执行

【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise

mise run（别名r）是 mise 的任务执行入口，负责发现、调度并运行项目中定义在mise.toml或任务目录里的各类任务，同时自动完成工具安装、依赖准备、输出控制与沙箱隔离。本文将围绕该命令的完整参数面展开，结合 docs/tasks/running-tasks.md、docs/tasks/task-configuration.md 与 src/cli/run.rs 的实现细节，帮助你掌握单任务/多任务执行、并行调度、输出模式、增量跳过、输出缓存与安全沙箱等完整用法，让构建、测试与 CI 脚本在团队和本地保持一致。

命令概览：用法、别名与默认行为

mise run的完整调用形式如下（usage 规范由 src/cli/run.rs 声明，本文档由 usage-cli 从该 spec 自动生成）：

mise run [FLAGS] [TASK] [ARGS]…

别名：mise r <task>完全等价于mise run <task>；在不会与未来新增命令冲突的前提下，还可以直接写mise <task>调用任务。官方建议在脚本和文档中始终使用mise run <task>形式，因为一旦未来 mise 增加了同名命令，裸任务名会被遮蔽（见 docs/tasks/running-tasks.md）。
位置：mise 自己的 flag 必须放在任务名之前，任务名之后的所有参数都会原样传给任务。
多任务调度：使用:::分隔符同时调度多个任务，例如mise run lint ::: test ::: check。
默认任务：不指定任务时，mise 会运行名为default的任务（若已定义）；否则在交互式终端中打开任务选择器。
任务来源：任务定义在mise.toml的[tasks.<name>]段，或mise-tasks/、.mise/tasks/等任务目录中的可执行脚本（文件任务），还可以通过[task_config].includes引入额外的 TOML 任务文件或远程git::任务（详见 docs/tasks/task-configuration.md）。

快速上手：三个任务示例

运行名为lint的任务（无论在mise.toml中定义还是作为独立脚本）：

mise run lint

强制运行build任务，即使其sources已经是最新状态：

mise run --force build

以原始 I/O 模式运行test（stdin/stdout/stderr 直连当前终端，强制--jobs=1防止输出交错）：

mise run --raw test

并行运行lint、test、check三个任务：

mise run lint ::: test ::: check

每个任务各自携带参数：

mise run cmd1 arg1 arg2 ::: cmd2 arg1 arg2

任务定义与增量执行：sources / outputs 新鲜度检查

一个典型的增量构建任务如下，适合已有 npm 构建脚本且依赖已安装的项目：

[tasks.build] run = "npm run build" sources = ["src/**/*.ts", "package.json", "package-lock.json"] outputs = ["dist/**/*.js"]

当任务同时声明了sources和outputs时，mise 会比较文件修改时间：若最旧输出文件的 mtime 比最新源文件的 mtime 更新，则认为输出是新鲜的，直接跳过任务执行。--force可绕过该新鲜度检查；而任务输出缓存（task output cache）则有一套独立的--task-cache控制开关。

关于该机制的补充要点（来自 docs/tasks/task-configuration.md）：

任务定义本身也自动作为 source 参与比较，因此编辑任务定义会触发重新执行。
sources支持 glob 与花括号备选（如src/**/*.{js,ts}），也支持!前缀排除（与 gitignore 约定一致），条目按顺序求值、后匹配者生效。
未声明outputs时默认是outputs = { auto = true }：mise 会 touch 一个基于任务定义哈希的内部标记文件（存储在~/.local/state/mise/task-outputs/<hash>），从而让sources变化即触发重跑。
mise watch也会使用sources决定监听哪些文件；mise watch build可在源文件变化时自动重跑任务。

更进一步的内容寻址输出缓存（实验性）由任务属性cache = { enabled = true, ... }开启，命中后可从缓存恢复已声明的输出文件并重放日志，详见 docs/tasks/caching.md。普通的新鲜度检查命中只是保留现有输出并跳过任务，两者机制对比如下：

机制	比较依据	命中时的行为
新鲜度检查（Freshness checks）	源文件与输出文件的修改时间	保留现有输出并跳过任务
输出缓存（Artifact cache）	声明的输入内容与其他缓存键材料	恢复声明的输出并重放捕获的日志

并行执行与执行顺序

默认并行度为 4，可通过--jobs（环境变量MISE_JOBS）、jobs设置或MISE_JOBS调整；--jobs小于 1 的值按 1 处理。

mise run --jobs 8 lint ::: test ::: check

当--jobs=1时，输出模式会被自动切换为interleave。任务之间的先后顺序由三种配置属性控制：

depends：前置依赖，必须在该任务之前完成；多个依赖之间按依赖图并行调度，depends中的书写顺序不构成先后顺序。依赖只运行一次（多个任务共享同一依赖时）。
wait_for：等待列出的任务完成，但不会把它们加入本次运行；只有当它们已被调度时才等待其结束。
depends_post：在该任务及其依赖完成后运行，适合清理类任务（如postlint）。
任务内部run数组中的{ task = "..." }/{ tasks = [...] }是执行步骤而非依赖边：前者按顺序等待完成，后者并行执行。

[tasks.build] run = "echo 'build'" [tasks.test] run = "echo 'test'" depends = ["build"]

[tasks.one_by_one] run = [ { task = "example1" }, # 等待 example1 完成后再继续 { tasks = ["example2", "example3"] }, # 这两个并行 ]

说明：mise tasks deps <task>只展示由depends/wait_for/depends_post构成的任务图，run数组中的{ task }引用不视为图边。

输出模式：样式与详细度正交

--output <OUTPUT>（环境变量MISE_TASK_OUTPUT）控制任务输出如何显示，可选值：

prefix（默认）——按行打印 stdout/stderr，并加上任务标签前缀，避免并行输出交错。
interleave——直接写 stdout/stderr，不按行缓冲。
replacing——stdout 每次被替换显示，stderr 原样打印。
timed——仅当 stdout 行显示超过 1 秒时才展示。
keep-order——按行打印并带任务标签前缀，同时保持输出顺序。
quiet——不显示额外输出。
silent——不显示任何输出（包括任务自身的 stdout/stderr，仅保留错误）。

输出样式（style）与详细度（verbosity）是正交的两条轴：

详细度开关：--quiet（MISE_QUIET）、--silent/-S（MISE_SILENT），以及设置中的quiet/silent或任务的quiet/silent属性。
两者可自由组合：例如MISE_TASK_OUTPUT=prefix配合--quiet会保留任务名前缀、同时隐藏 mise 自身的消息。--quiet不再强制取消前缀——想要旧的去前缀行为请用--output quiet或-o interleave。

任务级quiet（布尔）只隐藏 mise 自身的输出（如[build] $ cargo build），脚本自身输出保留；silent（布尔或"stdout"/"stderr"）则隐藏任务全部或指定流。

原始 I/O 与交互式任务

mise run --raw test：把 stdin/stdout/stderr 直连终端，不做逐行处理；此模式下不应用输出脱敏（redactions），并强制--jobs=1防止输出交错。可用raw配置或MISE_RAW环境变量持久化。
任务属性raw = true：按命令粒度独占终端锁，比--raw粒度更细，也不会全局强制单线程。
任务属性interactive = true：任务独占标准 I/O，运行期间阻塞其他所有任务；非交互任务之间仍可并行。
任务属性raw_args = true：mise 完全不解析任务参数，所有参数（含--help/-h）原样透传给底层命令，适合作为自带参数解析器的工具代理（如next build、manage.py）。

注意：默认情况下 stdin 是不连接的；raw/interactive任务都会绕过输出脱敏与产物缓存。

参数传递、usage 接口与`--`分隔符

任务名之后的一切都属于任务，因此：

mise run build --release

会把--release传给任务。若要给任务传--help/-h而避免被 mise 拦截，使用--分隔符：mise run task -- --help；mise run task -- -- --help则把-- --help原样传给任务（src/cli/run.rs 中args_last记录了--之后的参数并透传）。

没有usage定义时，多余参数的传递方式取决于任务形式：

run为数组时，参数只传给最后一个条目；
普通内联命令的参数以字面量追加（使用 shell 时做 shell 引用）；
shebang 文件任务按脚本执行，解释器以$1/$@正常暴露参数。

若想为任务声明经过校验的 CLI 接口（含参数验证、解析、自动补全与文档），可在任务上加usage字段，例如：

[tasks.test] usage = ''' arg "<file>" help="The file to test" default="src/main.rs" ''' run = 'cargo test ${usage_file?}'

usage 中的参数/flag 还支持env=声明环境变量作为备选来源，优先级为：命令行参数 > 环境变量 > 默认值。相关完整语法见 docs/tasks/task-arguments.md 与 docs/tasks/task-configuration.md。

任务分组与通配符

任务名可用:前缀进行语义分组，如test:unit、test:integration。TOML 键含冒号必须加引号：

[tasks."test:unit"] run = 'cargo test --lib'

mise run与依赖声明都支持 glob 通配符：

?匹配单个字符
*匹配单个:分组内的 0 或多个字符
**匹配 0 或多个完整:分组
{glob1,glob2,...}匹配任意逗号分隔的 glob
[ab,...]匹配字符集或范围（如[a-z]）
[!ab,...]匹配不在字符集内的任意字符

# 匹配 test:units:local，但不匹配 test:e2e:happy:local mise run 'test:*:local' # 匹配两者 mise run 'test:**:local' # 花括号组合 mise run 'generate:{completions,docs:*}'

依赖中同样可用：

[tasks."lint:eslint"] run = "eslint ." [tasks."lint:prettier"] run = "prettier --check ." [tasks.lint] depends = ["lint:*"] wait_for = ["render"]

迁移提示：旧版本中*可递归匹配嵌套分组；如需保留递归行为，请改用**。

工具与环境准备

mise run在启动任务前默认会做三件事：解析配置、安装缺失的工具（受task.run_auto_install设置控制）、运行[deps]中auto=true的依赖准备步骤。相关 flag：

-t, --tool <TOOL@VERSION>：在mise.toml之外临时附加工具，例如mise run -t node@20 python@3.10 build，格式为TOOL@VERSION。
--skip-tools：跳过任务前自动安装工具。可持久化为设置task.run_auto_install或环境变量MISE_TASK_RUN_AUTO_INSTALL=false。
--no-deps：跳过自动依赖准备（auto-enabled deps steps）。
--fresh-env：绕过环境缓存，重新计算环境（源码中通过env::reset_env_cache_key()重置环境缓存键，见 src/cli/run.rs）。
-s, --shell <SHELL>：指定运行 TOML 任务的内置 shell。Unix 默认为sh -o errexit -c，Windows 默认为cmd /c；可用设置MISE_UNIX_DEFAULT_INLINE_SHELL_ARGS/MISE_WINDOWS_DEFAULT_INLINE_SHELL_ARGS修改，或由任务自身的shell属性覆盖。

从源码看，任务执行前会构建 Toolset（ToolsetBuilder，离线解析版本元数据）、按需安装缺失工具、创建 lazy tools 的 shim，再运行 auto deps 引擎（src/cli/run.rs）。在 monorepo 中，任务解析阶段会把子目录配置并入工具集，确保子项目声明的工具在依赖步骤运行前已就绪。

此外，任务运行时会获得一组 mise 注入的环境变量，包括MISE_ORIGINAL_CWD、MISE_CONFIG_ROOT、MISE_PROJECT_ROOT、MISE_MONOREPO_ROOT、MISE_TASK_NAME、MISE_TASK_COLOR、MISE_TASK_DIR、MISE_TASK_FILE，详见 docs/tasks/index.md。

沙箱与权限控制（Linux/macOS/Windows 差异）

mise run提供细粒度的沙箱 flag，用于限制任务对文件系统、网络与环境的访问（具体平台支持差异见 docs/sandboxing.md）：

Flag	作用
`--deny-all`	阻断读、写、网络与全部环境变量继承
`--deny-read`	阻断文件系统读（系统库与工具目录仍可访问）
`--deny-write`	阻断全部文件系统写
`--deny-net`	阻断全部网络访问
`--deny-env`	阻断环境变量继承，仅保留`PATH`、`HOME`、`USER`、`SHELL`、`TERM`、`COLORTERM`、`LANG`
`--allow-read <PATH>`	仅允许从指定路径读取（隐含对其他读的拒绝）
`--allow-write <PATH>`	仅允许写入指定路径（隐含对其他写的拒绝，允许写即允许读）
`--allow-net <HOST>`	仅允许访问指定主机（隐含对其他网络的拒绝）
`--allow-env <VAR>`	仅允许指定环境变量（隐含对其他变量的拒绝），支持通配符如`--allow-env='MYAPP_*'`

平台限制提醒（来自命令文档原文）：Linux 不支持按主机过滤网络，会直接报错；macOS 的按主机过滤存在已知限制，详见沙箱指南；Windows 上沙箱不可用，mise 会告警并以无主机过滤的方式运行。

任务级配置中也有一一对应的属性：deny_all、deny_read、deny_write、deny_net、deny_env、allow_read、allow_write、allow_net、allow_env，以及实验性的pass_through_env（在拒绝环境继承时放行指定变量但不计入缓存键）。

任务输出缓存控制

任务输出缓存（artifact cache，实验性）与新鲜度检查是两套独立机制，由--task-cache <TASK_CACHE>（环境变量MISE_TASK_CACHE）控制本次运行的读写行为，可选值：

read-write（默认）——读取缓存结果并写入新结果
read-only——只读取缓存结果，不写入新结果
write-only——写入新结果，但总是实际执行而不恢复缓存
off——关闭任务输出缓存，仅使用 sources/outputs 新鲜度检查
local-only——只读写本地缓存（当前等价于read-write）

# 防止不可信的 PR 写入缓存条目 mise run --task-cache read-only test # 预热本地缓存但不消费现有条目 mise run --task-cache write-only build # 诊断任务，不读写任何输出产物 mise run --task-cache off --force build

配套的诊断 flag：

--task-cache-explain：打印生成每个任务输出缓存键的输入明细（只按类别和数量报告潜在敏感材料，不泄露内容）。
--task-cache-explain-json：以 JSON Lines 输出缓存键输入明细（要求配合--dry-run，且与--task-cache-explain互斥），不实际运行任务。
--task-cache-stats：报告缓存命中数/比例、恢复的字节数与节省的时间（与--dry-run冲突）。

--no-cache（环境变量MISE_TASK_REMOTE_NO_CACHE）则是另一回事：它关闭的是远程任务定义的获取缓存（即git::远程任务仓库的本地缓存），与输出缓存无关。缓存机制的完整说明见 docs/tasks/caching.md。

影响范围与增量选择：--affected 与 --all

针对 monorepo 场景，mise run提供基于 Git 变更的影响范围分析：

--affected：仅为受 Git 变更影响的项目运行匹配任务（需要 monorepo 根配置；源码中要求--affected必须存在 monorepo root，见 src/cli/run.rs）。
--affected-base <REV>：Git 基准修订，默认取MISE_AFFECTED_BASE、CI 元数据或HEAD~1。
--affected-head <REV>：Git 头修订，默认取MISE_AFFECTED_HEAD、CI 元数据或HEAD。
--affected-explain：解释项目与任务为何被选中。
--affected-json：以 JSON 输出受影响的项目与任务而不运行任务（与--affected-explain互斥，需--affected）。

影响分析会结合变更路径、workspace 全局输入与锁文件（cargo/go/node/uv 四种 workspace provider，见 src/cli/run.rs）计算受影响项目，并支持//...:task目标路径语法。完整说明见 docs/tasks/monorepo.md。

--all：在交互式选择器中展示整个 monorepo 的全部任务（与显式TASK和--affected冲突）。

其余执行控制 flag

-c, --continue-on-error：某个任务失败后继续运行其余任务。
-C, --cd <CD>：执行命令前切换到指定目录。
-n, --dry-run：不实际运行任务，仅按执行顺序打印任务列表（可用于预览依赖调度顺序）。
--skip-deps：只运行指定任务，跳过所有依赖（环境变量MISE_TASK_SKIP_DEPENDS；设置task.skip_depends也可持久化）。
--timeout <TIMEOUT>：整个任务运行的超时时间，如30s、5m；未指定时回退到全局设置中的 task 超时。单个任务也可声明timeout，两者取更短者生效。任务运行超时后源码会报错mise run timed out after ...（src/cli/run.rs）。
--no-timings：隐藏每个任务完成后的耗时打印；可用MISE_TASK_TIMINGS=0默认隐藏（MISE_TASK_TIMINGS=1默认显示）。
任务超时说明：任务级timeout与--timeout/全局设置并存时，较短的生效；--timeoutCLI 优先于全局设置。

完整 Flags 速查表

Flag	短选项	默认值 / 环境变量	说明
`--affected`	仅运行受 Git 变更影响的项目中的匹配任务
`--affected-base <REV>`	`MISE_AFFECTED_BASE`、CI 元数据或`HEAD~1`	Git 基准修订
`--affected-explain`	解释 --affected 的选中原因
`--affected-head <REV>`	`MISE_AFFECTED_HEAD`、CI 元数据或`HEAD`	Git 头修订
`--affected-json`	JSON 输出受影响项目/任务，不运行
`--all`	交互式选择器展示整个 monorepo 的任务
`--continue-on-error`	`-c`	失败后继续运行
`--cd <CD>`	`-C`	执行前切换目录
`--force`	`-f`	绕过新鲜度检查强制运行
`--jobs <JOBS>`	`-j`	`jobs`设置或`MISE_JOBS`	并行任务数，小于 1 按 1 处理
`--dry-run`	`-n`	仅按执行顺序打印任务
`--output <OUTPUT>`	`-o`	`MISE_TASK_OUTPUT`	输出样式：prefix/interleave/replacing/timed/keep-order/quiet/silent
`--quiet`	`-q`	`MISE_QUIET`	不显示额外输出
`--raw`	`-r`	`raw`配置 /`MISE_RAW`	直连 stdin/stdout/stderr，不做脱敏
`--shell <SHELL>`	`-s`	Unix 默认`sh -o errexit -c`，Windows 默认`cmd /c`	运行 TOML 任务所用 shell
`--silent`	`-S`	`MISE_SILENT`	除错误外不显示任何输出
`--tool <TOOL@VERSION>`	`-t`	追加工具，如`node@20`
`--allow-env <VAR>`	放行指定环境变量（支持通配符）
`--allow-net <HOST>`	放行指定主机网络
`--allow-read <PATH>`	放行指定路径读取
`--allow-write <PATH>`	放行指定路径写入
`--deny-all`	阻断读、写、网络与环境变量
`--deny-env`	阻断环境变量继承（保留基础变量）
`--deny-net`	阻断全部网络
`--deny-read`	阻断文件系统读
`--deny-write`	阻断文件系统写
`--fresh-env`	绕过环境缓存重新计算
`--no-cache`	`MISE_TASK_REMOTE_NO_CACHE`	远程任务不使用缓存
`--no-deps`	跳过自动依赖准备
`--no-timings`	`MISE_TASK_TIMINGS=0`	隐藏任务耗时
`--skip-deps`	`MISE_TASK_SKIP_DEPENDS`	仅运行指定任务、跳过依赖
`--skip-tools`	`task.run_auto_install`设置 /`MISE_TASK_RUN_AUTO_INSTALL=false`	跳过任务前工具安装
`--task-cache <MODE>`	`read-write`/`MISE_TASK_CACHE`	输出缓存读写模式
`--task-cache-explain`	解释输出缓存键输入
`--task-cache-explain-json`	JSON Lines 输出缓存键输入（需`--dry-run`）
`--task-cache-stats`	报告缓存命中统计
`--timeout <TIMEOUT>`	全局 task 超时设置	任务运行超时，如`30s`、`5m`

注意：任务名之后的参数全部归属任务，mise 自身 flag 必须放在任务名之前——mise run build --silent会把--silent当作任务参数，若任务未定义该参数会报unexpected word: --silent；正确写法是mise run --silent build。这也意味着任务可以自由定义与 mise flag 同名的参数，例如自己的--env。

实战工作流：从单任务到 monorepo

1. 本地快速验证

mise run test # 运行 test 任务 mise run --force build # 忽略新鲜度检查强制构建 mise run -n release # 先预览 release 及其依赖的执行顺序

2. CI 中跳过缓存写入

mise run --task-cache read-only --skip-tools test

3. 发布前完整流水线

mise run lint ::: test ::: check # 三路并行 mise run --timeout 5m release # 限制整体运行时间

4. monorepo 按变更范围执行

mise run --affected test # 只测受影响项目 mise run --affected-explain test # 查看选中原因 mise run --all # 交互式选择整个仓库的任务

5. 沙箱运行不受信任的任务

mise run --deny-net --deny-write build # 禁止网络与写盘 mise run --allow-env='MYAPP_*' --deny-env build # 仅放行指定变量

mise run 命令完全指南：任务调度、新鲜度检查、缓存与沙箱执行