如何用 mise tool-stub 在仓库中创建可移植的自包含工具脚本【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise你在仓库里写了一个脚本它需要用到特定版本的 Python 或 Node但希望别人 clone 仓库后直接运行./bin/py就能拿到正确的运行时而不是先各自装一遍环境。mise 的 tool stub 就是为此设计的一个以mise tool-stubshebang 开头的可执行文件内嵌一段 TOML 配置记录「用哪个工具、哪个版本、执行哪个二进制」。首次执行时 mise 会自动安装所需工具版本并转发参数。前提是运行机器上mise在PATH中除非用生成器的--bootstrap包装安装器。注意普通的mise install不会发现并安装仓库里任意位置的 stub 文件stub 只在被执行时才触发安装见 tool stub 文档。什么时候用 stub、什么时候不用文档给出了明确判断如果只是想在本机为一批普通工具做全局目录优先用[tools]里的lazy true当可执行文件本身就应该携带一份可移植、自包含的工具定义并随仓库分发时用 tool stub。准备条件运行机器上已安装mise且其在PATH中stub 的 shebang 是#!/usr/bin/env -S mise tool-stub靠env找到mise。仓库里建一个存放 stub 的目录下文统一用bin/你可以改成任何目录。后端 stub 需要所选后端能解析版本HTTP stub 则需要有效的下载 URL。手写一个后端 stub把 Python 3.14 固定进仓库这是最短主路径适用于 mise 后端已覆盖的工具python、node、gh 等。创建bin目录把下面的文件保存为bin/py#!/usr/bin/env -S mise tool-stub tool python version 3.14 bin python在 Unix 上赋予执行权限并运行chmod x ./bin/py ./bin/py --version ./bin/py -c import sys; print(sys.executable)几条关键说明文件名stub 名是py但实际执行的是已安装的python可执行文件stub 路径后面的参数全部转发给 Python。顶层不要像mise.toml那样包一层[tools]字段直接放在顶层。tool指定工具或后端例如python、github:cli/cli省略tool且有 URL 时会走 HTTP 后端否则 mise 用 stub 文件名当工具名。version默认latestbin默认取 stub 文件名。想要精确运行时写具体版本或 给 stub 加锁。shebang 里的-S是必需的Unix 的 shebang 传统上只支持解释器路径后跟一个参数-S让env按空格拆分命令行从而拆成env→mise→tool-stub。用生成器创建 HTTP stub内嵌下载地址、校验和与二进制路径工具只通过 HTTP 分发没有对应后端时手工写 URL、校验和、包内二进制路径容易出错用mise generate tool-stub生成更稳妥命令参考 mise generate tool-stub。单平台生成mise generate tool-stub ./bin/gh --url https://github.com/cli/cli/releases/download/v2.96.0/gh_2.96.0_linux_amd64.tar.gz执行时生成器会下载该归档并对这些字节记录校验和解包后自动探测二进制路径生成一个带下载与执行元数据的可执行 stub。生成的校验和用于检测 artifact 后续的变化但它本身不能认证首次下载发布者的身份——提交 stub 前请先审查 URL 并确保来源可信。生成后查看文件而不是手填校验和或大小cat ./bin/gh文件里包含从归档中发现的 URL、可执行路径、校验和与大小。version若是默认值latest可以省略。注意HTTP stub 里latest这个标签不会让版本化 URL 追踪新发布升级时要更新 URL 并重新生成元数据。输出文件名会成为工具名如果自动探测选错了可执行文件归档里含多个命令时尤其如此用--bin覆盖。多平台与增量构建mise generate tool-stub ./bin/rg \ --platform-url linux-x64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-x86_64-unknown-linux-musl.tar.gz \ --platform-url macos-arm64:https://github.com/BurntSushi/ripgrep/releases/download/14.0.3/ripgrep-14.0.3-aarch64-apple-darwin.tar.gzURL 里带平台信息时可以省略platform:前缀让 mise 从 URL 文件名自动探测# Auto-detect platform from URL (detects as macos-arm64) mise generate tool-stub ./bin/node \ --platform-url https://nodejs.org/dist/v22.17.1/node-v22.17.1-darwin-arm64.tar.gz也可以用同样的方式逐平台追加。生成器会把新平台合并进已有的[platforms]表而不是覆盖整个文件适合多次运行增量构建跨平台 stub重复指定某个平台会更新该条目所以提交前先检查 diff。文件名有歧义时用显式platform:前缀。常用生成选项来自 mise generate tool-stub 的参数说明--version VERSION指定工具版本默认latest。--bin PATH覆盖自动探测的包内二进制路径必须指向解包后仍会保留的那条相对路径归档根目录会被剥掉。--platform-url PLATFORM:URL/--platform-url URL平台特定 URL可重复不带前缀时从 URL 文件名自动探测平台。--platform-bin PLATFORM:PATH设置平台特定二进制路径。--checksum-algorithm ALGORITHM生成blake3默认或sha256校验和。面向要求 SHA256 的消费方例如 Bazel时mise generate tool-stub ./bin/tool \ --url https://example.com/tool.tar.gz \ --checksum-algorithm sha256--checksum-algorithm不能与--lock或--skip-download同时使用因为这两种模式不计算校验和。--skip-download不下载、不算校验和、不做二进制探测快速生成草稿生成后要先人工核对二进制路径再跑--fetch补齐元数据后才能依赖完整性检查。--fetch为已有 stub 中缺失的校验和与大小字段下载补齐URL 必须已在 stub 中。--lock解析版本并把锁数据精确版本 平台 URL/校验和嵌入已有 stub。--bootstrap用 bootstrap 脚本包装 stub若预期路径下没有 mise 就先安装 mise 再执行 stub。生成器自动识别的归档格式.tar.gz/.tgz、.tar.xz/.txz、.tar.bz2/.tbz2、.tar.zst/.tzst、.zip、.7z。手写 HTTP stub 的配置形态不用生成器时顶层 URL 对所有运行平台生效只适用于在所有这些机器上兼容的 artifact#!/usr/bin/env -S mise tool-stub url https://example.com/releases/1.0.0/tool.tar.gzOS 或架构相关的二进制改用[platforms]表上面的 URL 是文档占位符实际请用生成器记录真实下载元数据#!/usr/bin/env -S mise tool-stub [platforms.linux-x64] url https://example.com/releases/1.0.0/tool-linux-x64.tar.gz [platforms.macos-arm64] url https://example.com/releases/1.0.0/tool-macos-arm64.tar.gzbin是相对已安装目录的路径且在任何归档根目录被剥掉之后生效各平台包结构不同时再写平台特定bin#!/usr/bin/env -S mise tool-stub # Global bin field used when platforms have the same structure bin bin/tool [platforms.linux-x64] url https://example.com/tool-linux.tar.gz # Uses global bin field: bin/tool [platforms.windows-x64] url https://example.com/tool-windows.zip bin tool.exe # Platform-specific binary for Windows存在 URL 且没有tool字段时stub 默认走 HTTP 后端完整配置见 HTTP backend 文档。URL 支持模板变量见 HTTP backend 的 Template Variables 一节#!/usr/bin/env -S mise tool-stub version 1.0.0 [platforms.linux-x64] url https://releases.example.com/v{{version}}/tool-linux-x64.tar.gz [platforms.macos-arm64] url https://releases.example.com/v{{version}}/tool-macos-arm64.tar.gz其中{{version}}会被替换为 stub 里的version值os()、arch()等模板函数同理。给后端 stub 加锁固定精确版本与下载元数据后端 stub 想记录精确版本及其后端能提供的平台下载元数据时用--lock# Create a stub with a fuzzy version mise generate tool-stub ./bin/node --version 24 # Lock it to pin the exact version and add platform URLs/checksums mise generate tool-stub ./bin/node --lock生成器把结果写进 stub 的[lock]段顶层tool仍选择后端version变成解析后的精确版本。默认解析当前及常见平台linux-x64、linux-x64-musl、linux-arm64、linux-arm64-musl、macos-x64、macos-arm64、windows-x64若配置了lockfile_platforms则使用那些平台加当前平台。锁数据里的 URL 可以省去后续安装时的 release 发现过程但不会免除私有下载的认证也不会省掉各后端的验证与策略请求提交前审查生成的平台表与校验和。升级锁定 stub 时把--version和--lock一起传# Select Node.js 26 and regenerate the locked metadata mise generate tool-stub ./bin/node --lock --version 26运行与验证直接执行Unixchmod x ./bin/my-tool ./bin/my-tool --versionWindows 不能执行 shebang 脚本所以mise generate tool-stub会在 stub 旁生成一个.cmd启动器通过PATHEXT按名字运行.\bin\my-tool.cmd --version启动器的生成规则stub 列出[platforms.windows-*]条目、或根本没列平台时会生成只服务 Linux/macOS 的 stub 不会生成stub 自身名字已以.cmd、.bat、.exe结尾的也不会。启动器在所有平台上都会写入因此 Linux 上生成并提交到仓库的 stubWindows 用户 clone 下来同样能用。如果 stub 后来不再支持 Windows重新生成会移除启动器只有 mise 生成的启动器会被移除你自己写的不会被动。无扩展名的 stub 文件也保留Git Bash 和 Cygwin 会经由 shebang 运行它。调试时用mise tool-stub命令直接执行 stub参数会原样转发必要时用--分隔 mise 参数与工具参数mise tool-stub ./bin/my-tool --version行为上需要注意每次调用 stub 都经过 mise。stub 有查找缓存按 stub 文件路径与修改时间建立文件变化自动失效二进制缺失会触发缓存清理但脚本里重复调用同一工具时文档建议用mise exec一次性准备好环境再在脚本里直接调用工具。执行过的 stub 会被记录到~/.local/state/mise/tracked-stubsmise prune把被跟踪 stub 引用的工具版本视为必需不会删除它们。前提是 stub 在该机器上至少执行过一次stub 文件被删后其工具版本又可被 prune。替代路径用mise x写简单包装脚本基础用例也可以不写 TOML用mise x写 bash 包装# Create a simple Node.js stub cat ./bin/node EOF #!/usr/bin/env bash exec mise x node24 -- node $ EOF chmod x ./bin/node--后面的命令是核心mise x node24选择运行时node $指明可执行文件并保留调用方参数。这类包装依赖 Bash 和 mise且不内嵌 artifact 元数据——需要平台映射或内嵌锁数据时用 TOML stub 格式。限制与不适用场景stub 要求PATH中有mise目标机器无法预装 mise 时用生成器的--bootstrap生成自带安装器的包装可用--bootstrap-version固定 mise 版本。mise install不会扫描仓库里的 stub 并安装其工具安装只发生在 stub 被执行的时机。HTTP stub 的校验和只检测 artifact 变化不构成对发布者身份的认证。生成器示例中的 URL 多为占位符如https://example.com/...实际提交前请替换为真实下载地址或用--skip-download先出草稿再人工补全。【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考