Aqua 后端

Aqua 工具可以在 mise 中原生使用。aqua 是新工具的理想后端，因为它们不需要插件，支持 Windows，并且除了校验和之外还提供安全功能。aqua 的安装过程还会显示更多进度条，这一点很不错。

你不需要单独安装 aqua。mise 中完全不会使用 aqua CLI。实际使用的是 aqua registry，它会在发布时编译进 mise 可执行文件中。这里有一个包条目的示例：aqua:hashicorp/terraform。 mise 内置了一个 aqua 的重新实现，它知道如何处理这些文件来安装工具。

默认情况下，使用内置的快照。启用 registry_floating 设置后，会先检查当前的官方 aqua registry，同时保留内置快照作为备用。它还会让 mise 的简写 registry 跟随更新；有关其中的权衡和缓存行为，请参阅浮动 registry。

截至目前，aqua 对 mise 来说还比较新，并且由于许多工具正在从 asdf 转换为 aqua，aqua 工具中的一些配置可能需要进一步完善。下面列出了一些常见问题，如果你发现问题，强烈建议将修改贡献回 aqua registry。维护者响应非常迅速，也非常乐于合作。

如果其他方法都失败了，你可以通过 MISE_DISABLE_BACKENDS=aqua 完全禁用 aqua。

目前，aqua 工具不支持设置环境变量，也不支持除了简单下载二进制文件之外的更多功能（而且我也不确定这一功能将来是否会被加入），因此某些工具很可能始终需要像 asdf/vfox 这样的插件。

这段代码位于 mise 仓库中的 ./src/backend/aqua.rs。

自定义注册表

设置 aqua.registries，即可在内置注册表之前检查自定义 aqua 注册表源：

toml

[settings]
aqua.registries = ["https://github.com/my-org/aqua-registry"]

要在内置注册表之前检查多个注册表，请按顺序列出它们：

toml

[settings]
aqua.registries = [
  "https://github.com/my-org/internal-aqua-registry",
  "https://github.com/partner/aqua-registry",
]

每个源可以是仓库 URL、直接指向 registry.yaml 或 registry.yml 文件的 URL，或者使用绝对路径 file:// URL 指定的本地目录或注册表文件：

toml

[settings]
aqua.registries = [
  "file:///absolute/path/to/aqua-registry",
  "file:///absolute/path/to/registry.yaml",
  "https://example.com/registry.yaml",
]

对于仓库和目录源，mise 会从源根目录加载 registry.yaml，如有需要则回退到 registry.yml。远程注册表源会根据 aqua.registry_cache_ttl 缓存到 MISE_CACHE_DIR 下，该设置默认为一周。本地 file:// 源会绕过下载源缓存，因此注册表下次加载时会读取更改后的内容。在 MISE_AQUA_REGISTRIES 中，请使用逗号分隔多个注册表 URL。

当刷新后的注册表源被下载后，mise 会对该源进行哈希处理，并使用该哈希作为编译后注册表缓存路径的一部分。当新的编译缓存成功加载或写入时，会清理同一注册表 URL 的旧编译缓存。

包的解析会按配置的注册表顺序进行检查。当启用 aqua.baked_registry 时，内置注册表仍会作为所有已配置注册表中缺失包的回退。 Aqua 注册表别名仅在定义它们的注册表内有效；当你希望 mise 的简写或别名指向来自其他注册表的 aqua 包时，请使用 [tool_alias]。

旧版的 aqua.registry_url 设置仍然支持单个注册表 URL，但当两者都设置时，aqua.registries 优先。

使用

下面的命令会安装 ripgrep 的最新版本，并将其设置为 PATH 上的活动版本：

$ mise use -g aqua:BurntSushi/ripgrep
$ rg --version
ripgrep 14.1.1

该版本将以以下格式写入 ~/.config/mise/config.toml：

toml

[tools]
"aqua:BurntSushi/ripgrep" = "latest"

如果某些工具在 registry/ 中被指定为使用 aqua 后端，它们将默认使用 aqua。要查看这些工具，请运行 mise registry | grep aqua:。

工具选项

`symlink_bins`

有些工具会捆绑额外的可执行文件，这些文件你可能不希望暴露在 PATH 上。例如，aws-cli 会捆绑 Python，这可能会与你期望使用的 Python 版本冲突。

设置 symlink_bins = true 会创建一个经过筛选的 .mise-bins 目录，只暴露 mise 打算为该 Aqua 包公开的二进制文件，而不是从安装中发现的所有可执行文件。

toml

[tools]
aws-cli = { version = "latest", symlink_bins = true }

启用后：

如果 aqua registry 定义了 files 字段，则只会暴露那些二进制文件（例如 aws-cli 的 aws 和 aws_completer）
否则，mise 会回退为暴露该包推断出的主二进制文件
会创建一个 .mise-bins 子目录，并为暴露的二进制文件创建符号链接
捆绑的依赖项和其他额外可执行文件，例如 aws-cli 中的 Python，不会被添加到 PATH

`vars`

某些 aqua registry 条目定义了模板变量（例如 {{.Vars.channel}}）。可通过工具选项来设置它们，既可以使用顶层键，也可以使用嵌套的 vars 表：

toml

[tools]
"aqua:flutter/flutter" = { version = "3.32.8", channel = "stable" }
"aqua:scenarigo/scenarigo" = { version = "0.21.0", vars = { go_version = "1.24" } }

带默认值的变量会自动填充。aqua registry 中标记为必需的变量必须设置，除非该 registry 也提供了默认值。

`prerelease`

默认情况下，GitHub 上标记为 prerelease: true 的发布不会被包含在 mise ls-remote 和 latest 解析中。设置 prerelease = true 以包含它们：

toml

[tools]
"aqua:owner/tool" = { version = "latest", prerelease = true }

设置后，预发布标签（例如 v1.0.0-rc1、v0.1.2-dev.86）会出现在 mise ls-remote 中，latest 会基于包含预发布版本的完整列表进行解析，模糊版本查询也会匹配预发布标签。当包使用 github_tag 版本源时无效（git 标签不携带 prerelease 标记）。草稿发布始终被排除。更多细节请参见 github 后端文档。

设置

`aqua.baked_registry`

Type: boolean
Env: MISE_AQUA_BAKED_REGISTRY
Default: true

Use baked-in aqua registry.

`aqua.cosign`

Type: boolean
Env: MISE_AQUA_COSIGN
Default: true

Use cosign to verify aqua tool signatures.

`aqua.github_attestations`

Type: boolean
Env: MISE_AQUA_GITHUB_ATTESTATIONS
Default: true

Enable/disable GitHub Artifact Attestations verification for aqua tools. When enabled, mise will verify the authenticity and integrity of downloaded tools using GitHub's artifact attestation system.

`aqua.minisign`

Type: boolean
Env: MISE_AQUA_MINISIGN
Default: true

Use minisign to verify aqua tool signatures.

`aqua.registries`

Type: string[](optional)
Env: MISE_AQUA_REGISTRIES(comma separated)
Default: None

Aqua registry sources to load before the baked-in registry. Each source can be a repository URL, a direct URL to a registry.yaml or registry.yml file, or an absolute file:// URL to a local registry directory or file. For repository and directory sources, mise loads registry.yaml from the source root and falls back to registry.yml if needed.

A source that is not a URL is read as a filesystem path, resolved against the config root of the file that declared it. This is how you reference a registry committed alongside the project:

[settings]
aqua.registries = ["registry.yaml"]

Path resolution applies only to sources set in a config file, since only those have a config root to resolve against. A path given via MISE_AQUA_REGISTRIES or the CLI must be an absolute file:// URL.

Downloaded registries are cached according to aqua.registry_cache_ttl, which defaults to one week. To refresh sooner, run mise cache clear, set aqua.registry_cache_ttl = "0s", or change MISE_CACHE_DIR to use a different cache location. Local file:// sources bypass the downloaded source cache, so changes are read the next time the registry is loaded.

If this is set, mise checks the configured registries in order. When aqua.baked_registry is enabled, the baked-in aqua registry remains a fallback for packages missing from all configured registries.

By default, mise uses the baked-in official aqua registry when aqua.baked_registry is enabled. If the baked registry is disabled and no registries are configured, mise downloads the official registry: https://github.com/aquaproj/aqua-registry

`aqua.registry_cache_ttl`

Type: string
Env: MISE_AQUA_REGISTRY_CACHE_TTL
Default: 1w

How long downloaded aqua registry source files remain fresh before mise re-downloads them.

When the downloaded source changes, mise writes the new source cache atomically, compiles a new source-hash-scoped registry cache, and prunes older compiled caches for that registry URL after the new compiled cache is available.

Set to 0s to re-download remote registries every time.

`aqua.registry_url`deprecated

Type: string(optional)
Env: MISE_AQUA_REGISTRY_URL
Default: None
Deprecated: Use aqua.registries instead.

Deprecated. Use aqua.registries instead.

Legacy single aqua registry repository URL to fetch before the baked-in registry.

`aqua.slsa`

Type: boolean
Env: MISE_AQUA_SLSA
Default: true

Use SLSA to verify aqua tool signatures.

安全验证

Aqua 后端支持多种安全验证方法，以确保下载工具的完整性和真实性。mise 为所有验证方法提供了原生 Rust 实现，无需依赖 cosign、slsa-verifier 或 gh 等外部 CLI 工具。

GitHub 制品证明

GitHub 制品证明提供加密证明，表明制品是由特定的 GitHub Actions 工作流构建的。mise 原生验证这些证明，以确保下载工具的真实性和完整性。

要求：

工具必须在 aqua 注册表中配置 github_artifact_attestations，才能验证证明
不需要外部工具——验证由 mise 原生处理

配置：

bash

# 启用/禁用 GitHub 制品证明验证（默认：true）
export MISE_AQUA_GITHUB_ATTESTATIONS=true

注册表配置示例：

yaml

packages:
  - type: github_release
    repo_owner: cli
    repo_name: cli
    github_artifact_attestations:
      signer_workflow: cli/cli/.github/workflows/deployment.yml

Cosign 验证

mise 原生验证 Cosign 签名，无需安装 cosign CLI 工具。

配置：

bash

# 启用/禁用 Cosign 验证（默认：true）
export MISE_AQUA_COSIGN=true

SLSA 溯源验证

mise 原生验证 SLSA（软件制品供应链级别）溯源，无需安装 slsa-verifier CLI 工具。

配置：

bash

# 启用/禁用 SLSA 验证（默认：true）
export MISE_AQUA_SLSA=true

其他安全方法

Aqua 还支持：

Minisign 验证：使用 minisign 进行签名验证
校验和验证：验证 SHA256/SHA512/SHA1/MD5 校验和（始终启用）

验证流程

在安装工具期间，mise 将：

下载工具及其签名/证明文件
使用配置的方法进行原生验证
通过进度指示器显示验证状态
如果任何验证失败，则中止安装

安装期间的示例输出：

✓ 已下载 cli/cli v2.50.0
✓ GitHub 制品证明已验证
✓ 工具安装成功

故障排查

如果验证失败：

检查网络连接：验证需要下载证明数据
验证工具配置：确保 aqua 注册表具有正确的验证设置
禁用特定验证：临时禁用有问题的验证方法
启用调试日志：使用 MISE_DEBUG=1 查看详细的验证日志

常见问题：

未找到证明：该工具可能未在注册表中配置证明
验证超时：网络问题或证明服务响应缓慢
证书验证：时钟偏差或证书链问题

要临时禁用所有验证：

bash

export MISE_AQUA_GITHUB_ATTESTATIONS=false
export MISE_AQUA_COSIGN=false
export MISE_AQUA_SLSA=false
export MISE_AQUA_MINISIGN=false

常见的 aqua 问题

以下是我在使用 aqua 工具时见过的一些常见问题。

缺少受支持的环境

aqua 注册表为每个工具定义了 os/arch 的支持环境。我注意到其中一些只是缺少实际上受支持的 os/arch 组合——这可能是因为该工具的注册表创建之后才加入的。

修复很简单，只需编辑相关工具 registry.yaml 中的 supported_envs 部分即可。

使用 `version_filter` 而不是 `version_prefix`

这是一个很奇怪的问题，会在 mise 中引发奇怪的故障。一般来说，在 mise 里我们喜欢像 1.2.3 这样的版本号，不带 v1.2.3 或 cli-v1.2.3 之类的装饰。这种一致性不仅让 mise.toml 更简洁，也有助于像 mise up 这样的功能正常工作，因为它能够把它解析为 semver，而不用处理一堆边缘情况。

实际上，如果你注意到 aqua 工具给出的版本号不是简单的三段式，那么值得修正。

我见过的一个常见情况是，注册表使用了像 Version startsWith "Version startsWith "atlascli/"" 这样的 version_filter 表达式。

这最终会导致版本变成 atlascli/1.2.3，而这不是我们想要的。修复方法是使用 version_prefix 而不是 version_filter，并且只把前缀放到 version_prefix 字段里。在这个例子中，它应该是 atlascli/。mise 会自动把它去掉并在需要时再加回去，而这对 version_filter 做不到。

Aqua 后端 ​

自定义注册表 ​

使用 ​

工具选项 ​

symlink_bins ​

vars ​

prerelease ​

设置 ​

aqua.baked_registry

aqua.cosign

aqua.github_attestations

aqua.minisign

aqua.registries

aqua.registry_cache_ttl

aqua.registry_urldeprecated

aqua.slsa

安全验证 ​

GitHub 制品证明 ​

Cosign 验证 ​

SLSA 溯源验证 ​

其他安全方法 ​

验证流程 ​

故障排查 ​

常见的 aqua 问题 ​

缺少受支持的环境 ​

使用 version_filter 而不是 version_prefix ​

Aqua 后端

自定义注册表

使用

工具选项

`symlink_bins`

`vars`

`prerelease`

设置

`aqua.baked_registry`

`aqua.cosign`

`aqua.github_attestations`

`aqua.minisign`

`aqua.registries`

`aqua.registry_cache_ttl`

`aqua.registry_url`deprecated

`aqua.slsa`

安全验证

GitHub 制品证明

Cosign 验证

SLSA 溯源验证

其他安全方法

验证流程

故障排查

常见的 aqua 问题

缺少受支持的环境

使用 `version_filter` 而不是 `version_prefix`