2026/9/10 15:23:11
FEATURED · 精选文章 
mise.lock 锁文件完全指南锁定工具版本、校验和与可复现安装【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/misemise.lock是 misedev tools、env vars、task runner项目中用于锁定已解析工具版本与产物校验和的锁文件mise.toml记录项目接受的版本请求mise.lock记录这些请求最终解析到的具体版本支持的后端还会记录产物的下载 URL、校验和与验证元数据。本文完整讲解锁文件的启用方式、TOML 文件格式、环境/全局/本地/Monorepo 锁文件、严格锁定模式、mise lock --bump自动依赖更新工作流、后端支持差异与安全模型并给出可直接复制的命令与配置示例。概述为什么需要锁文件锁文件把例行安装与有意升级分离开来。日常开发中执行mise install安装的永远是锁定的版本而升级只发生在显式执行更新命令时mise lock # 解析已配置的工具但不安装 mise install # 安装锁文件中记录的具体版本 mise lock --bump node # 在 node 的配置请求范围内重新解析到最新版本提交更新前务必先审查锁文件的 diff。需要明确的是锁定工具版本并不等于锁定应用依赖——mise.lock不锁定你的应用包如 npm 依赖、系统库也不锁定外部安装器拉取的全部传递依赖。因此package-lock.json、uv.lock等生态锁文件仍需照常维护。锁文件中存储的 URL 可以减少发布发现的 API 调用次数但私有下载、未缓存的产物以及验证或策略检查仍可能需要网络访问与认证。相关细节见下文 后端支持 一节与 GitHub tokens。启用锁文件执行mise lock可以显式创建项目锁文件。若希望工具安装或升级时自动创建并维护锁文件在mise.toml中配置[settings] lockfile true如果想为所有项目设置个人默认值mise settings set lockfiletrue从源码角度看锁文件相关的设置行为在 src/config/settings.rs 中有清晰划分lockfile_enabled()在lockfile未设置时默认返回true即更新现有锁文件而lockfile_creation_enabled()仅在lockfile Some(true)时才为真即自动创建新锁文件。这正是文档中未设置时mise 会更新已有锁文件但不会自动创建新文件的底层逻辑。MISE_LOCKFILE1环境变量保留更新已有文件这一兼容行为它不等同于在 TOML 中显式配置lockfile true。全局锁文件只能通过mise lock --global创建。工作原理锁文件创建与更新配置lockfile true后运行mise install或mise use会以实际安装的精确版本创建或更新mise.lock当lockfile未设置时这些命令只更新已有锁文件而不创建新文件。版本解析复用mise 会复用与当前配置请求、后端和选项完全匹配的既有锁条目。校验和验证对支持的后端mise 会存储并校验所下载工具的校验和。mise lock不仅解析配置级工具也解析各个任务task中声明的工具。它会读取任务定义包括继承的模板和被 include 的任务文件但不会运行任务本身、任务依赖、hooks 或工具安装器。这保证了任务专属工具可以在首次执行任务之前就被锁定。这些条目使用相同的[[tools.*]]格式写入拥有该任务的配置对应的锁文件。对应实现可见 src/cli/lock.rs该命令会加载config.tasks_with_context并把任务工具纳入待锁定集合。文件格式锁文件是 TOML 格式。下面是一个精简示例展示了一个请求如何绑定到具体版本以及单个平台上的产物元数据如何存储。请用mise lock生成项目实际需要的条目不要直接复制本示例lockfile_version 1 [[tools.node]] version 26.8.1 backend core:node specifiers [26.8.1] [tools.node.platforms.macos-arm64] checksum sha256:6e577fd0d9db776db82306629e441a9dace416702622aebdd171c9dfaa41f4d2 url https://nodejs.org/dist/v26.8.1/node-v26.8.1-darwin-arm64.tar.gz格式版本与升级新锁文件使用当前带版本号的格式。当前实现中CURRENT_LOCKFILE_VERSION为1见 src/lockfile.rs 中const CURRENT_LOCKFILE_VERSION: u32 1。无版本号的旧锁文件被视作版本 0普通更新时保持该格式以避免意外的锁文件漂移读取到高于当前支持版本的锁文件会直接报错源码中bail!(unsupported lockfile version ...)。执行mise lock --upgrade可有意升级旧格式锁文件。版本 1 的关键改进把每个原始工具请求specifiers记录在其解析到的具体条目上因此1与1.0.0这类重叠请求可以可靠地选择不同的锁定版本。源码中bind_request()会按(version, options)定位目标条目并把 specifier 绑定到其上。平台信息Platform Information平台条目以带引号的键写入例如[tools.node.platforms.macos-arm64]。平台标识通常是os-arch其元数据可能包含checksum可选用于完整性验证的 SHA256 或 Blake3 哈希size遗留字段文件字节数读取旧锁文件时接受但当前写入器不再输出url可选产物下载 URLurl_api可选API 下载 URL用于需要认证资产请求的源provenance与provenance_verified可用的验证方式以及验证是否成功signer与attested_byPackslip 的身份承诺工具条目字段Tool Entry Fields每个工具条目[[tools.name]]可以包含version必填工具的精确版本backend可选安装工具所用的后端如core:node、aqua:BurntSushi/ripgrepspecifiers版本 1解析到该版本及选项变体的原始请求options可选标识产物的后端特定选项如{exe rg, matching musl}platforms可选平台特定元数据校验和、URL、大小当产物的身份不仅取决于平台键时同一版本的工具可以拥有多条条目。例如 Swift 为每个 Linux 发行版发布不同的 tarball因此其条目会记录各自描述的对象[[tools.swift]] version 6.3.1 backend core:swift options { swift_platform ubuntu24.04 } [[tools.swift]] version 6.3.1 backend core:swift options { swift_platform fedora39 }条目按 options精确匹配因此某台机器只会针对自己发行版对应的条目做验证。可以通过swift.platform固定让所有 Linux 机器解析到同一产物并提交该条目。若某平台没有对应产物例如ubi9没有 arm64 构建该平台会被报告为skipped而不是锁定。平台键Platform Keys平台键格式通常为os-arch但可由后端自定义标准格式linux-x64、macos-arm64、windows-x64后端特定部分后端如 Java可能使用更具体的平台标识工具特定ubi等后端可能在平台键中包含额外的工具特定信息环境特定锁文件使用 环境特定配置文件例如mise.test.toml时每个环境拥有独立的锁文件配置文件锁文件mise.tomlmise.lockmise.test.tomlmise.test.lockmise.staging.tomlmise.staging.lockmise.local.tomlmise.local.lockmise.test.local.tomlmise.test.local.lock例如设置MISE_ENVtest时MISE_ENVtest mise lock # 同时创建 mise.lock 和 mise.test.lock来自mise.toml的工具写入mise.lock来自mise.test.toml的工具写入mise.test.lock。解析规则当MISE_ENVtest时mise 为mise.test.toml中定义的工具读取mise.test.lock为mise.toml中的工具读取mise.lock。环境特定锁文件严格限定在其对应配置的范围内——只包含该配置定义的工具。这种设计意味着不设置MISE_ENV的 CI 环境只依赖mise.lock因此mise.dev.lock中的开发工具版本升级不会使 CI 缓存失效。mise.lock与mise.env.lock都应提交到版本控制mise.local.lock与mise.env.local.lock则应与其对应配置文件一起加入.gitignore。环境文件的本地变体约定可参考 docs/configuration/environments.md。全局锁文件全局配置~/.config/mise/config.toml中声明的工具不会被普通的mise lock锁定——普通命令只针对当前活动的项目配置根。请使用mise lock --globalmise lock --global # 更新全局及系统配置锁文件::: tip 当全局配置是指向 dotfiles 仓库的符号链接时也是如此例如~/.config/mise/config.toml-~/dotfiles/mise.toml。mise 通过两条路径访问同一个文件并视为全局配置因此在仓库内运行mise lock会提示项目范围内未配置任何工具。请改用mise lock --global锁文件会写在符号链接目标旁边~/dotfiles/mise.lock。 :::本地锁文件mise.local.toml通常已被 gitignore中定义的工具使用独立的mise.local.lock文件将本地工具配置与已提交的锁文件分离# mise.local.toml 的工具写入 mise.local.lock mise use --path mise.local.toml node22 # 常规 mise.toml 工具写入 mise.lock mise use --path mise.toml node20使用mise lock --local更新所有平台的本地锁文件mise lock --local # 更新 mise.local.lock mise lock --local node python # 更新 mise.local.lock 中的指定工具在 src/cli/lock.rs 中--local与--global是互斥的目标选择参数分别作用于本地配置与全局/系统配置的锁文件集合。Monorepo当monorepo_root true时mise 可以在 Monorepo 根目录使用单一锁文件。设置[monorepo] lockfile true可启用根锁文件变体如mise.lock、mise.ci.lock与mise.local.lock[monorepo] lockfile true已有子项目锁文件会在下一次锁感知命令执行时迁移进根锁文件。不设置该配置则保持各子项目独立锁文件便于逐步推广。使用mise*.lock文件的 Monorepo 会在 mise2026.12.0开始收到警告未设置默认值将在 mise2027.6.0切换到根锁文件。旧版 mise 无法理解这种布局下的子项目工具归属需要兼容混合版本的项目可以固定旧行为[monorepo] lockfile false详见 Monorepo 任务。源码中migrate_monorepo_lockfiles与monorepo_lockfile_union见 src/lockfile.rs 与 src/cli/lock.rs负责子项目锁文件向根锁文件的合并与迁移并保证 monorepo 场景下mise lock不会误把根配置自身的条目当作过期数据清理掉。严格锁文件模式locked设置在通过支持 URL 锁定的后端安装工具前要求锁文件中存在当前平台的 URL。它能在安装阶段捕获缺失的产物解析而不是静默解析它不是离线模式且部分后端豁免。# 启用严格模式 mise settings set lockedtrue # 或通过环境变量 MISE_LOCKED1 mise install默认情况下调用级锁定模式作用于 project项目、user-global用户全局与 system系统配置。使用locked_scopes排除那些有意包含滚动版本或发行版托管工具的作用域# 位于 ~/.config/mise/config.toml 或 /etc/mise/config.toml [settings] locked true locked_scopes [project]合法作用域为project、global、systemsrc/config/settings.rs 中对非法值会报错 expected one of: project, global, system。显式工具参数与环境提供的工具版本仍然保持锁定因为它们不属于某个配置作用域。排除某作用域只是放宽该作用域的锁定模式mise 在存在锁文件时仍会使用既有锁文件。若全局工具需要锁定但锁文件中缺失运行mise lock -g生成全局锁文件。locked_scopes仅限全局设置项目配置无法削弱用户的锁定策略。若只想对单一配置根声明的工具强制执行严格模式使用tool_config.locked代替调用级设置[tool_config] locked true [tools] node 24该策略属于所在配置根mise.toml、mise.local.toml及共享该根的其他配置声明的工具都必须存在于各自锁文件中。从全局或父配置根继承的工具保留自己的策略。即使某作用域被locked_scopes排除配置根级策略仍然生效。启用后若某工具在锁文件中没有当前平台的 URLmise install会失败。修复方式是先用mise lock填充 URLmise lock # 刷新已有平台或为新文件生成默认平台集 mise lock --platform linux-x64,macos-arm64 # 或指定平台该检查只覆盖能记录 URL 的后端。asdf、cargo、gem、go、npm、pipx、ubi、core:dotnet、core:rust、core:swift通过外部工具安装或在安装时解析下载vfox 的backend插件尚无法上报 URL因此严格模式会跳过它们而不是失败——混合使用这些工具与可锁定工具的项目仍能安装。vfox 的tool插件能记录 URL会像其他可锁定后端一样被检查。由 tool stub 解析的工具同样跳过。各后端记录内容的明细见下文 后端支持。严格模式建议在 CI 中使用以捕获受支持后端的锁条目缺失。注意验证与认证下载仍可能发起 API 请求。工作流初始设置# 生成锁文件 mise lock # 使用锁定版本安装工具 mise install日常使用# 从锁文件安装精确版本 mise install # 更新工具与锁文件 mise upgrade更新版本# 更新 mise.toml 中的工具版本 mise use node26 # 这会同时更新安装与 mise.lock推进锁定版本Bump Locked Versionsmise lock --bump会针对模糊版本选择器如latest、lts或22这类前缀重新解析到最新匹配版本并更新锁文件——不安装任何东西也不修改mise.toml。精确固定的版本保持不变改写mise.toml中的固定版本请使用mise upgrade --bump# mise.toml 中 node 22 锁定在 22.14.0此后发布了 22.15.0 mise lock --bump # 锁文件现在固定 22.15.0mise.toml 仍写着 22 mise lock --bump node # 只推进 node mise lock --bump --dry-run # 只展示将发生的变更不写入该能力专为自动化依赖更新设计在 CI 上定时运行锁文件变化时打开 PR。--json以机器可读格式输出变更并抑制人类可读输出。只有版本级变更会被报告——版本未变时的校验和/URL 刷新不会产生条目——且版本列表保持配置/锁文件顺序而非排序。从配置中移除的工具会以空的new_versions报告mise lock --bump --dry-run --json[ { name: node, backend: core:node, lockfile: ~/src/myproj/mise.lock, old_versions: [22.14.0], new_versions: [22.15.0] } ]--json输出结构对应源码 src/cli/lock.rs 中的LockChange序列化结构name、backend、lockfile、old_versions、new_versions其compute_version_changes仅在新旧版本集合不同时才生成变更条目并刻意不做版本排序。::: tip 在安全模式下运行 bump 自动化 当任务针对你无法控制的配置运行时——最常见的是机器人程序在 PR 分支上 bumpmise.lock——设置MISE_SAFE1以防止项目配置执行代码。安全模式会拒绝模板exec()、_.source脚本、hooks、tasks、asdf 插件脚本与插件安装而--bump基于 HTTP 后端的版本解析仍正常工作MISE_SAFE1 mise lock --bump --json:::固定锁定版本Pinning a Locked Version可以在保持mise.toml中模糊选择器不变的同时在锁文件里固定某个具体版本# mise.toml 中是 node latest 或 node 22 mise upgrade node22.15.0 # 安装 22.15.0 并更新 mise.lock mise lock node22.15.0 # 不重装仅更新 mise.lock若指定版本与当前配置前缀不匹配配置会被自动更新。例如mise.toml中为node 20执行mise upgrade node22.15.0后配置会被更新为node 22保持同样的精度级别锁文件设置为22.15.0。该行为对应源码中compute_config_bumps_for_paths与apply_config_bumps的实现——--bump模式下明确跳过配置改写Never under --bump, which is documented to leave config files untouched。各命令与锁文件的交互下表展示每个命令如何与mise.toml和mise.lock交互命令安装更新mise.toml更新mise.lockmise use node22是是设置node 22是mise install是否是mise install node是否是安装 node 的配置版本mise install node22.15.0是否否一次性安装非配置驱动mise upgrade是否是mise upgrade node是否是在范围内升级 nodemise upgrade node22.15.0是仅当版本不匹配前缀时是mise upgrade --bump是是前缀推进以匹配是mise lock否否是为所有工具重新生成mise lock --bump否否是选择器重新解析到最新mise lock node22.15.0否仅当版本不匹配前缀时是要点mise use改变所选配置文件通常是mise.toml中请求的版本mise install安装配置中的内容而不修改它——mise install node安装配置版本的 node 并更新锁文件而mise install node22.15.0是一次性安装不更新锁文件mise upgrade在配置范围内升级工具并更新锁文件——传toolversion可指定具体版本mise lock不安装只重新生成锁条目——传toolversion可固定具体版本--bump把模糊选择器推进到最新匹配版本后端支持请检查生成的实际条目确认当前工具与平台。支持程度因后端、工具选项以及发布物是预编译产物还是源码构建而异后端家族可预期的内容下载型后端如 aqua、GitHub/GitLab/Forgejo、HTTP 与 S3源提供或 mise 可计算的平台产物元数据Packslip签名产物信息与签名者承诺策略在安装时检查内置语言工具特定支持Node、Python、Ruby 有产物解析路径外部安装器则有不同限制语言包安装器顶层工具版本不会锁定所有传递包或构建输入vfox tool 插件插件 hook 提供的下载 URL 可参与严格 URL 锁定asdf 与 vfox backend 插件无严格 URL 锁定要求插件执行仍决定安装方式provenance字段与经过密码学验证的 provenance 结果是两种不同状态。在把锁文件元数据当作验证证据前请先阅读 来源与安全。最佳实践版本控制更改请求时将项目配置与锁文件一起提交git add mise.toml mise.lock git commit -m chore: update development tools环境锁文件与其共享配置一同提交。.local变体不进入版本控制。审查变更时除版本号外还要关注产物 URL、后端 options 与验证元数据。团队工作流用mise use更改请求或用mise lock --bump tool推进既有请求。运行mise install与项目相关检查。提交审查过的配置与锁文件变更。拉取代码后团队成员运行mise install安装记录中的版本。任何更新项目的人都可以遵循此流程锁文件变更不需要单独的团队角色。CI/CD检出仓库并安装 mise 后- name: Install locked tools run: mise install env: MISE_LOCKED: 1提交锁文件前先为 runner 的平台准备条目。若使用jdx/mise-action它也提供工具安装与缓存请把锁文件保留在该 action 使用的 checkout 中。缓存能加速安装但不能替代锁文件或其检查。故障排查重新生成校验和校验和不匹配意味着下载的字节与记录的产物不一致。先核对错误与锁文件中的工具、平台、URL 与后端 options。可能的原因厂商替换了资源、镜像提供了不同内容或条目描述的是另一个构建。确认为有意的上游变更后只刷新受影响工具的元数据并审查 diffmise lock node git diff -- mise.lock把node替换为受影响工具。不要删除校验和或卸载所有工具来绕过失败。如果新产物出乎意料请保留现有锁文件在接受新字节前调查发布源。Ruby 预编译构建修订版发布预编译 Ruby 二进制可能对同一 Ruby 版本存在构建修订版发布。锁文件保持version 3.3.11但在平台url中固定所选构建修订url https://github.com/jdx/ruby/releases/download/3.3.11-1/ruby-3.3.11.x86_64_linux.tar.gz这里3.3.11-1表示构建修订1。关于修订存在的原因、未锁定安装的行为以及如何更新旧锁文件参见 Ruby 预编译构建修订。锁文件冲突合并不同锁文件的分支时先在配置中解决预期的版本请求。解决锁文件冲突同时保留相应的请求绑定与平台条目。运行mise lock刷新元数据并检查其 diff。运行mise install与相关项目检查然后提交结果。为特定项目禁用# 位于项目的 mise.toml [settings] lockfile false从其他工具迁移从 asdf 迁移预览导入现有版本文件然后生成配置mise generate config --tool-versions .tool-versions --dry-run mise generate config --tool-versions .tool-versions --yes mise lock mise install在没有现有mise.toml的项目中使用此流程或把预览审查合并进现有文件。若团队成员仍在使用 asdf请保持共享的.tool-versions一致参见 asdf 迁移。从 package.json engines 迁移engines.node通常描述的是兼容范围如22而不是精确版本请求。为项目选择一个受支持的 Node.js 版本并显式锁定mise use node24 mise lock node启用 惯用版本文件 后mise 会在自动项目发现中读取受支持的devEngines字段。不要把任意 npm 范围语法直接传给mise use。来源与安全对受支持的后端mise lock会记录可用的 provenance 元数据例如 SLSA、Cosign、Minisign 或 GitHub attestations。Aqua 与 GitHub 可以在锁定期间下载并密码学验证当前平台的产物。成功的检查会以provenance_verified单独记录。跨平台元数据可能描述了一种可用的验证方式但并未在本地验证过。源码中 src/lockfile.rs 的ProvenanceType枚举定义了 Minisign、Cosign、SLSA可携带.intoto.jsonl的 URL与 GitHub Attestations 四种机制及其优先级顺序低到高Minisign Cosign SLSA GithubAttestations验证时按优先级尝试。安装期间校验和加已记录的已验证 provenance 结果可以让 mise 跳过重复的 provenance 检查。因此锁文件是信任输入审查它并从可信的项目来源获取。产物校验和验证始终生效。仅有 provenance 字段并不证明字节被验证过。如果 GitHub Artifact Attestations 已启用但 GitHub API 确认某个校验和后端产物不存在任何 attestationmise 可能记录github_attestations unavailable。这是一个否定缓存条目不是 provenance它只在后续从该锁文件安装时跳过冗余的 GitHub attestation 探测。SLSA、Cosign、Minisign 与校验和验证等其他验证路径照常运行。GitHub 的文档展示了用actions/attest从已有产物路径生成二进制 attestationREST API 按 subject digest 列出 attestations。这意味着 attestation 可能出现在 release 资源上传之后。之后的mise lock运行或MISE_LOCKED_VERIFY_PROVENANCE1 mise install可以发现锁文件记录为 unavailable 之后新增的 attestation。需要更高安全性时可以强制每次安装都重新验证 provenance[settings] locked_verify_provenance true或通过环境变量MISE_LOCKED_VERIFY_PROVENANCE1 mise install这在 paranoid 模式下也会自动启用[settings] paranoid true启用后对正在安装的产物会重新运行受支持的验证路径而不是信任之前锁文件中的验证结果。这不会为从未发布过 provenance 的 release 创造 provenance已安装的工具可能不会被重新下载。它与 Packslip 签名者及签名列表策略相互独立。相关实现中设置locked_verify_provenance与paranoid的合并逻辑见 src/config/settings.rsself.locked_verify_provenance || self.paranoid。最小发布年龄Minimum Release Age除锁文件外mise 使用minimum_release_age设置限制供应链风险——只安装已发布满一定时长的版本。默认值为24h[settings] minimum_release_age 7d # 覆盖默认的 24h 延迟这与锁文件配合良好——用minimum_release_age避免选中刚发布的新版本用锁文件固定经过你验证的精确版本。该设置过滤顶层模糊版本解析针对提供发布时间的后端。无时间戳的版本默认包含在内。目前只有npm:与pipx:会把同一截止时间转发到传递依赖解析。其他后端可能选择较旧的顶层工具版本但不会约束工具安装器/编译器拉取的依赖。mise lock还提供--minimum-release-age命令行参数别名--before支持绝对日期如2024-06-01与相对时长如90d或1y只影响20或latest这类模糊匹配精确固定的版本不受过滤既有匹配的锁条目会被保留。参见配置设置 —— 全部可用设置工具版本管理 —— 工具版本的工作方式后端 —— 后端特定的校验和支持GitHub tokens —— 私有下载与认证Monorepo 任务 —— Monorepo 锁文件细节安全模式 —— bump 自动化中的MISE_SAFE1paranoid 模式 —— 强制 provenance 重新验证【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
mise.lock 锁文件完全指南：锁定工具版本、校验和与可复现安装
mise.lock 锁文件完全指南锁定工具版本、校验和与可复现安装【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/misemise.lock是 misedev tools、env vars、task runner项目中用于锁定已解析工具版本与产物校验和的锁文件mise.toml记录项目接受的版本请求mise.lock记录这些请求最终解析到的具体版本支持的后端还会记录产物的下载 URL、校验和与验证元数据。本文完整讲解锁文件的启用方式、TOML 文件格式、环境/全局/本地/Monorepo 锁文件、严格锁定模式、mise lock --bump自动依赖更新工作流、后端支持差异与安全模型并给出可直接复制的命令与配置示例。概述为什么需要锁文件锁文件把例行安装与有意升级分离开来。日常开发中执行mise install安装的永远是锁定的版本而升级只发生在显式执行更新命令时mise lock # 解析已配置的工具但不安装 mise install # 安装锁文件中记录的具体版本 mise lock --bump node # 在 node 的配置请求范围内重新解析到最新版本提交更新前务必先审查锁文件的 diff。需要明确的是锁定工具版本并不等于锁定应用依赖——mise.lock不锁定你的应用包如 npm 依赖、系统库也不锁定外部安装器拉取的全部传递依赖。因此package-lock.json、uv.lock等生态锁文件仍需照常维护。锁文件中存储的 URL 可以减少发布发现的 API 调用次数但私有下载、未缓存的产物以及验证或策略检查仍可能需要网络访问与认证。相关细节见下文 后端支持 一节与 GitHub tokens。启用锁文件执行mise lock可以显式创建项目锁文件。若希望工具安装或升级时自动创建并维护锁文件在mise.toml中配置[settings] lockfile true如果想为所有项目设置个人默认值mise settings set lockfiletrue从源码角度看锁文件相关的设置行为在 src/config/settings.rs 中有清晰划分lockfile_enabled()在lockfile未设置时默认返回true即更新现有锁文件而lockfile_creation_enabled()仅在lockfile Some(true)时才为真即自动创建新锁文件。这正是文档中未设置时mise 会更新已有锁文件但不会自动创建新文件的底层逻辑。MISE_LOCKFILE1环境变量保留更新已有文件这一兼容行为它不等同于在 TOML 中显式配置lockfile true。全局锁文件只能通过mise lock --global创建。工作原理锁文件创建与更新配置lockfile true后运行mise install或mise use会以实际安装的精确版本创建或更新mise.lock当lockfile未设置时这些命令只更新已有锁文件而不创建新文件。版本解析复用mise 会复用与当前配置请求、后端和选项完全匹配的既有锁条目。校验和验证对支持的后端mise 会存储并校验所下载工具的校验和。mise lock不仅解析配置级工具也解析各个任务task中声明的工具。它会读取任务定义包括继承的模板和被 include 的任务文件但不会运行任务本身、任务依赖、hooks 或工具安装器。这保证了任务专属工具可以在首次执行任务之前就被锁定。这些条目使用相同的[[tools.*]]格式写入拥有该任务的配置对应的锁文件。对应实现可见 src/cli/lock.rs该命令会加载config.tasks_with_context并把任务工具纳入待锁定集合。文件格式锁文件是 TOML 格式。下面是一个精简示例展示了一个请求如何绑定到具体版本以及单个平台上的产物元数据如何存储。请用mise lock生成项目实际需要的条目不要直接复制本示例lockfile_version 1 [[tools.node]] version 26.8.1 backend core:node specifiers [26.8.1] [tools.node.platforms.macos-arm64] checksum sha256:6e577fd0d9db776db82306629e441a9dace416702622aebdd171c9dfaa41f4d2 url https://nodejs.org/dist/v26.8.1/node-v26.8.1-darwin-arm64.tar.gz格式版本与升级新锁文件使用当前带版本号的格式。当前实现中CURRENT_LOCKFILE_VERSION为1见 src/lockfile.rs 中const CURRENT_LOCKFILE_VERSION: u32 1。无版本号的旧锁文件被视作版本 0普通更新时保持该格式以避免意外的锁文件漂移读取到高于当前支持版本的锁文件会直接报错源码中bail!(unsupported lockfile version ...)。执行mise lock --upgrade可有意升级旧格式锁文件。版本 1 的关键改进把每个原始工具请求specifiers记录在其解析到的具体条目上因此1与1.0.0这类重叠请求可以可靠地选择不同的锁定版本。源码中bind_request()会按(version, options)定位目标条目并把 specifier 绑定到其上。平台信息Platform Information平台条目以带引号的键写入例如[tools.node.platforms.macos-arm64]。平台标识通常是os-arch其元数据可能包含checksum可选用于完整性验证的 SHA256 或 Blake3 哈希size遗留字段文件字节数读取旧锁文件时接受但当前写入器不再输出url可选产物下载 URLurl_api可选API 下载 URL用于需要认证资产请求的源provenance与provenance_verified可用的验证方式以及验证是否成功signer与attested_byPackslip 的身份承诺工具条目字段Tool Entry Fields每个工具条目[[tools.name]]可以包含version必填工具的精确版本backend可选安装工具所用的后端如core:node、aqua:BurntSushi/ripgrepspecifiers版本 1解析到该版本及选项变体的原始请求options可选标识产物的后端特定选项如{exe rg, matching musl}platforms可选平台特定元数据校验和、URL、大小当产物的身份不仅取决于平台键时同一版本的工具可以拥有多条条目。例如 Swift 为每个 Linux 发行版发布不同的 tarball因此其条目会记录各自描述的对象[[tools.swift]] version 6.3.1 backend core:swift options { swift_platform ubuntu24.04 } [[tools.swift]] version 6.3.1 backend core:swift options { swift_platform fedora39 }条目按 options精确匹配因此某台机器只会针对自己发行版对应的条目做验证。可以通过swift.platform固定让所有 Linux 机器解析到同一产物并提交该条目。若某平台没有对应产物例如ubi9没有 arm64 构建该平台会被报告为skipped而不是锁定。平台键Platform Keys平台键格式通常为os-arch但可由后端自定义标准格式linux-x64、macos-arm64、windows-x64后端特定部分后端如 Java可能使用更具体的平台标识工具特定ubi等后端可能在平台键中包含额外的工具特定信息环境特定锁文件使用 环境特定配置文件例如mise.test.toml时每个环境拥有独立的锁文件配置文件锁文件mise.tomlmise.lockmise.test.tomlmise.test.lockmise.staging.tomlmise.staging.lockmise.local.tomlmise.local.lockmise.test.local.tomlmise.test.local.lock例如设置MISE_ENVtest时MISE_ENVtest mise lock # 同时创建 mise.lock 和 mise.test.lock来自mise.toml的工具写入mise.lock来自mise.test.toml的工具写入mise.test.lock。解析规则当MISE_ENVtest时mise 为mise.test.toml中定义的工具读取mise.test.lock为mise.toml中的工具读取mise.lock。环境特定锁文件严格限定在其对应配置的范围内——只包含该配置定义的工具。这种设计意味着不设置MISE_ENV的 CI 环境只依赖mise.lock因此mise.dev.lock中的开发工具版本升级不会使 CI 缓存失效。mise.lock与mise.env.lock都应提交到版本控制mise.local.lock与mise.env.local.lock则应与其对应配置文件一起加入.gitignore。环境文件的本地变体约定可参考 docs/configuration/environments.md。全局锁文件全局配置~/.config/mise/config.toml中声明的工具不会被普通的mise lock锁定——普通命令只针对当前活动的项目配置根。请使用mise lock --globalmise lock --global # 更新全局及系统配置锁文件::: tip 当全局配置是指向 dotfiles 仓库的符号链接时也是如此例如~/.config/mise/config.toml-~/dotfiles/mise.toml。mise 通过两条路径访问同一个文件并视为全局配置因此在仓库内运行mise lock会提示项目范围内未配置任何工具。请改用mise lock --global锁文件会写在符号链接目标旁边~/dotfiles/mise.lock。 :::本地锁文件mise.local.toml通常已被 gitignore中定义的工具使用独立的mise.local.lock文件将本地工具配置与已提交的锁文件分离# mise.local.toml 的工具写入 mise.local.lock mise use --path mise.local.toml node22 # 常规 mise.toml 工具写入 mise.lock mise use --path mise.toml node20使用mise lock --local更新所有平台的本地锁文件mise lock --local # 更新 mise.local.lock mise lock --local node python # 更新 mise.local.lock 中的指定工具在 src/cli/lock.rs 中--local与--global是互斥的目标选择参数分别作用于本地配置与全局/系统配置的锁文件集合。Monorepo当monorepo_root true时mise 可以在 Monorepo 根目录使用单一锁文件。设置[monorepo] lockfile true可启用根锁文件变体如mise.lock、mise.ci.lock与mise.local.lock[monorepo] lockfile true已有子项目锁文件会在下一次锁感知命令执行时迁移进根锁文件。不设置该配置则保持各子项目独立锁文件便于逐步推广。使用mise*.lock文件的 Monorepo 会在 mise2026.12.0开始收到警告未设置默认值将在 mise2027.6.0切换到根锁文件。旧版 mise 无法理解这种布局下的子项目工具归属需要兼容混合版本的项目可以固定旧行为[monorepo] lockfile false详见 Monorepo 任务。源码中migrate_monorepo_lockfiles与monorepo_lockfile_union见 src/lockfile.rs 与 src/cli/lock.rs负责子项目锁文件向根锁文件的合并与迁移并保证 monorepo 场景下mise lock不会误把根配置自身的条目当作过期数据清理掉。严格锁文件模式locked设置在通过支持 URL 锁定的后端安装工具前要求锁文件中存在当前平台的 URL。它能在安装阶段捕获缺失的产物解析而不是静默解析它不是离线模式且部分后端豁免。# 启用严格模式 mise settings set lockedtrue # 或通过环境变量 MISE_LOCKED1 mise install默认情况下调用级锁定模式作用于 project项目、user-global用户全局与 system系统配置。使用locked_scopes排除那些有意包含滚动版本或发行版托管工具的作用域# 位于 ~/.config/mise/config.toml 或 /etc/mise/config.toml [settings] locked true locked_scopes [project]合法作用域为project、global、systemsrc/config/settings.rs 中对非法值会报错 expected one of: project, global, system。显式工具参数与环境提供的工具版本仍然保持锁定因为它们不属于某个配置作用域。排除某作用域只是放宽该作用域的锁定模式mise 在存在锁文件时仍会使用既有锁文件。若全局工具需要锁定但锁文件中缺失运行mise lock -g生成全局锁文件。locked_scopes仅限全局设置项目配置无法削弱用户的锁定策略。若只想对单一配置根声明的工具强制执行严格模式使用tool_config.locked代替调用级设置[tool_config] locked true [tools] node 24该策略属于所在配置根mise.toml、mise.local.toml及共享该根的其他配置声明的工具都必须存在于各自锁文件中。从全局或父配置根继承的工具保留自己的策略。即使某作用域被locked_scopes排除配置根级策略仍然生效。启用后若某工具在锁文件中没有当前平台的 URLmise install会失败。修复方式是先用mise lock填充 URLmise lock # 刷新已有平台或为新文件生成默认平台集 mise lock --platform linux-x64,macos-arm64 # 或指定平台该检查只覆盖能记录 URL 的后端。asdf、cargo、gem、go、npm、pipx、ubi、core:dotnet、core:rust、core:swift通过外部工具安装或在安装时解析下载vfox 的backend插件尚无法上报 URL因此严格模式会跳过它们而不是失败——混合使用这些工具与可锁定工具的项目仍能安装。vfox 的tool插件能记录 URL会像其他可锁定后端一样被检查。由 tool stub 解析的工具同样跳过。各后端记录内容的明细见下文 后端支持。严格模式建议在 CI 中使用以捕获受支持后端的锁条目缺失。注意验证与认证下载仍可能发起 API 请求。工作流初始设置# 生成锁文件 mise lock # 使用锁定版本安装工具 mise install日常使用# 从锁文件安装精确版本 mise install # 更新工具与锁文件 mise upgrade更新版本# 更新 mise.toml 中的工具版本 mise use node26 # 这会同时更新安装与 mise.lock推进锁定版本Bump Locked Versionsmise lock --bump会针对模糊版本选择器如latest、lts或22这类前缀重新解析到最新匹配版本并更新锁文件——不安装任何东西也不修改mise.toml。精确固定的版本保持不变改写mise.toml中的固定版本请使用mise upgrade --bump# mise.toml 中 node 22 锁定在 22.14.0此后发布了 22.15.0 mise lock --bump # 锁文件现在固定 22.15.0mise.toml 仍写着 22 mise lock --bump node # 只推进 node mise lock --bump --dry-run # 只展示将发生的变更不写入该能力专为自动化依赖更新设计在 CI 上定时运行锁文件变化时打开 PR。--json以机器可读格式输出变更并抑制人类可读输出。只有版本级变更会被报告——版本未变时的校验和/URL 刷新不会产生条目——且版本列表保持配置/锁文件顺序而非排序。从配置中移除的工具会以空的new_versions报告mise lock --bump --dry-run --json[ { name: node, backend: core:node, lockfile: ~/src/myproj/mise.lock, old_versions: [22.14.0], new_versions: [22.15.0] } ]--json输出结构对应源码 src/cli/lock.rs 中的LockChange序列化结构name、backend、lockfile、old_versions、new_versions其compute_version_changes仅在新旧版本集合不同时才生成变更条目并刻意不做版本排序。::: tip 在安全模式下运行 bump 自动化 当任务针对你无法控制的配置运行时——最常见的是机器人程序在 PR 分支上 bumpmise.lock——设置MISE_SAFE1以防止项目配置执行代码。安全模式会拒绝模板exec()、_.source脚本、hooks、tasks、asdf 插件脚本与插件安装而--bump基于 HTTP 后端的版本解析仍正常工作MISE_SAFE1 mise lock --bump --json:::固定锁定版本Pinning a Locked Version可以在保持mise.toml中模糊选择器不变的同时在锁文件里固定某个具体版本# mise.toml 中是 node latest 或 node 22 mise upgrade node22.15.0 # 安装 22.15.0 并更新 mise.lock mise lock node22.15.0 # 不重装仅更新 mise.lock若指定版本与当前配置前缀不匹配配置会被自动更新。例如mise.toml中为node 20执行mise upgrade node22.15.0后配置会被更新为node 22保持同样的精度级别锁文件设置为22.15.0。该行为对应源码中compute_config_bumps_for_paths与apply_config_bumps的实现——--bump模式下明确跳过配置改写Never under --bump, which is documented to leave config files untouched。各命令与锁文件的交互下表展示每个命令如何与mise.toml和mise.lock交互命令安装更新mise.toml更新mise.lockmise use node22是是设置node 22是mise install是否是mise install node是否是安装 node 的配置版本mise install node22.15.0是否否一次性安装非配置驱动mise upgrade是否是mise upgrade node是否是在范围内升级 nodemise upgrade node22.15.0是仅当版本不匹配前缀时是mise upgrade --bump是是前缀推进以匹配是mise lock否否是为所有工具重新生成mise lock --bump否否是选择器重新解析到最新mise lock node22.15.0否仅当版本不匹配前缀时是要点mise use改变所选配置文件通常是mise.toml中请求的版本mise install安装配置中的内容而不修改它——mise install node安装配置版本的 node 并更新锁文件而mise install node22.15.0是一次性安装不更新锁文件mise upgrade在配置范围内升级工具并更新锁文件——传toolversion可指定具体版本mise lock不安装只重新生成锁条目——传toolversion可固定具体版本--bump把模糊选择器推进到最新匹配版本后端支持请检查生成的实际条目确认当前工具与平台。支持程度因后端、工具选项以及发布物是预编译产物还是源码构建而异后端家族可预期的内容下载型后端如 aqua、GitHub/GitLab/Forgejo、HTTP 与 S3源提供或 mise 可计算的平台产物元数据Packslip签名产物信息与签名者承诺策略在安装时检查内置语言工具特定支持Node、Python、Ruby 有产物解析路径外部安装器则有不同限制语言包安装器顶层工具版本不会锁定所有传递包或构建输入vfox tool 插件插件 hook 提供的下载 URL 可参与严格 URL 锁定asdf 与 vfox backend 插件无严格 URL 锁定要求插件执行仍决定安装方式provenance字段与经过密码学验证的 provenance 结果是两种不同状态。在把锁文件元数据当作验证证据前请先阅读 来源与安全。最佳实践版本控制更改请求时将项目配置与锁文件一起提交git add mise.toml mise.lock git commit -m chore: update development tools环境锁文件与其共享配置一同提交。.local变体不进入版本控制。审查变更时除版本号外还要关注产物 URL、后端 options 与验证元数据。团队工作流用mise use更改请求或用mise lock --bump tool推进既有请求。运行mise install与项目相关检查。提交审查过的配置与锁文件变更。拉取代码后团队成员运行mise install安装记录中的版本。任何更新项目的人都可以遵循此流程锁文件变更不需要单独的团队角色。CI/CD检出仓库并安装 mise 后- name: Install locked tools run: mise install env: MISE_LOCKED: 1提交锁文件前先为 runner 的平台准备条目。若使用jdx/mise-action它也提供工具安装与缓存请把锁文件保留在该 action 使用的 checkout 中。缓存能加速安装但不能替代锁文件或其检查。故障排查重新生成校验和校验和不匹配意味着下载的字节与记录的产物不一致。先核对错误与锁文件中的工具、平台、URL 与后端 options。可能的原因厂商替换了资源、镜像提供了不同内容或条目描述的是另一个构建。确认为有意的上游变更后只刷新受影响工具的元数据并审查 diffmise lock node git diff -- mise.lock把node替换为受影响工具。不要删除校验和或卸载所有工具来绕过失败。如果新产物出乎意料请保留现有锁文件在接受新字节前调查发布源。Ruby 预编译构建修订版发布预编译 Ruby 二进制可能对同一 Ruby 版本存在构建修订版发布。锁文件保持version 3.3.11但在平台url中固定所选构建修订url https://github.com/jdx/ruby/releases/download/3.3.11-1/ruby-3.3.11.x86_64_linux.tar.gz这里3.3.11-1表示构建修订1。关于修订存在的原因、未锁定安装的行为以及如何更新旧锁文件参见 Ruby 预编译构建修订。锁文件冲突合并不同锁文件的分支时先在配置中解决预期的版本请求。解决锁文件冲突同时保留相应的请求绑定与平台条目。运行mise lock刷新元数据并检查其 diff。运行mise install与相关项目检查然后提交结果。为特定项目禁用# 位于项目的 mise.toml [settings] lockfile false从其他工具迁移从 asdf 迁移预览导入现有版本文件然后生成配置mise generate config --tool-versions .tool-versions --dry-run mise generate config --tool-versions .tool-versions --yes mise lock mise install在没有现有mise.toml的项目中使用此流程或把预览审查合并进现有文件。若团队成员仍在使用 asdf请保持共享的.tool-versions一致参见 asdf 迁移。从 package.json engines 迁移engines.node通常描述的是兼容范围如22而不是精确版本请求。为项目选择一个受支持的 Node.js 版本并显式锁定mise use node24 mise lock node启用 惯用版本文件 后mise 会在自动项目发现中读取受支持的devEngines字段。不要把任意 npm 范围语法直接传给mise use。来源与安全对受支持的后端mise lock会记录可用的 provenance 元数据例如 SLSA、Cosign、Minisign 或 GitHub attestations。Aqua 与 GitHub 可以在锁定期间下载并密码学验证当前平台的产物。成功的检查会以provenance_verified单独记录。跨平台元数据可能描述了一种可用的验证方式但并未在本地验证过。源码中 src/lockfile.rs 的ProvenanceType枚举定义了 Minisign、Cosign、SLSA可携带.intoto.jsonl的 URL与 GitHub Attestations 四种机制及其优先级顺序低到高Minisign Cosign SLSA GithubAttestations验证时按优先级尝试。安装期间校验和加已记录的已验证 provenance 结果可以让 mise 跳过重复的 provenance 检查。因此锁文件是信任输入审查它并从可信的项目来源获取。产物校验和验证始终生效。仅有 provenance 字段并不证明字节被验证过。如果 GitHub Artifact Attestations 已启用但 GitHub API 确认某个校验和后端产物不存在任何 attestationmise 可能记录github_attestations unavailable。这是一个否定缓存条目不是 provenance它只在后续从该锁文件安装时跳过冗余的 GitHub attestation 探测。SLSA、Cosign、Minisign 与校验和验证等其他验证路径照常运行。GitHub 的文档展示了用actions/attest从已有产物路径生成二进制 attestationREST API 按 subject digest 列出 attestations。这意味着 attestation 可能出现在 release 资源上传之后。之后的mise lock运行或MISE_LOCKED_VERIFY_PROVENANCE1 mise install可以发现锁文件记录为 unavailable 之后新增的 attestation。需要更高安全性时可以强制每次安装都重新验证 provenance[settings] locked_verify_provenance true或通过环境变量MISE_LOCKED_VERIFY_PROVENANCE1 mise install这在 paranoid 模式下也会自动启用[settings] paranoid true启用后对正在安装的产物会重新运行受支持的验证路径而不是信任之前锁文件中的验证结果。这不会为从未发布过 provenance 的 release 创造 provenance已安装的工具可能不会被重新下载。它与 Packslip 签名者及签名列表策略相互独立。相关实现中设置locked_verify_provenance与paranoid的合并逻辑见 src/config/settings.rsself.locked_verify_provenance || self.paranoid。最小发布年龄Minimum Release Age除锁文件外mise 使用minimum_release_age设置限制供应链风险——只安装已发布满一定时长的版本。默认值为24h[settings] minimum_release_age 7d # 覆盖默认的 24h 延迟这与锁文件配合良好——用minimum_release_age避免选中刚发布的新版本用锁文件固定经过你验证的精确版本。该设置过滤顶层模糊版本解析针对提供发布时间的后端。无时间戳的版本默认包含在内。目前只有npm:与pipx:会把同一截止时间转发到传递依赖解析。其他后端可能选择较旧的顶层工具版本但不会约束工具安装器/编译器拉取的依赖。mise lock还提供--minimum-release-age命令行参数别名--before支持绝对日期如2024-06-01与相对时长如90d或1y只影响20或latest这类模糊匹配精确固定的版本不受过滤既有匹配的锁条目会被保留。参见配置设置 —— 全部可用设置工具版本管理 —— 工具版本的工作方式后端 —— 后端特定的校验和支持GitHub tokens —— 私有下载与认证Monorepo 任务 —— Monorepo 锁文件细节安全模式 —— bump 自动化中的MISE_SAFE1paranoid 模式 —— 强制 provenance 重新验证【免费下载链接】misedev tools, env vars, task runner项目地址: https://gitcode.com/GitHub_Trending/mi/mise创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
