Mise 中文文档

外观

S3 后端 ​

你可以使用 s3 后端直接从 Amazon S3 或与 S3 兼容的存储（如 MinIO）安装工具。对于在私有 S3 存储桶中托管专有工具的企业团队来说，此后端非常理想。

其代码位于 mise 仓库中的 ./src/backend/s3.rs。

用法 ​

以下命令从 S3 存储桶安装一个工具：

sh
mise use -g "s3:my-tool[url=s3://my-bucket/tools/my-tool-v1.0.0.tar.gz]@1.0.0"

版本将以以下格式设置在 ~/.config/mise/config.toml 中：

toml
[tools]
"s3:my-tool" = { version = "1.0.0", url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz" }

身份验证 ​

S3 后端使用 AWS SDK 的默认凭证链。凭证按以下顺序加载：

  1. 环境变量：AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY
  2. AWS 凭证文件：~/.aws/credentials
  3. IAM 角色（在 AWS 基础设施上运行时）
sh
# 通过环境变量设置凭证
export AWS_ACCESS_KEY_ID="your-access-key"
export AWS_SECRET_ACCESS_KEY="your-secret-key"
export AWS_DEFAULT_REGION="us-east-1"

mise install

工具选项 ​

以下 tool-options 适用于 s3 后端——这些配置放在 mise.toml 的 [tools] 中。

url（必需） ​

指定用于下载工具的 S3 URL。该 URL 支持使用 {{ version }} 进行模板替换：

toml
[tools]
"s3:my-tool" = { version = "1.0.0", url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz" }

endpoint ​

为 MinIO、DigitalOcean Spaces 或自托管 S3 等服务指定自定义的 S3 兼容端点：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
endpoint = "http://minio.internal:9000"

region ​

指定 S3 存储桶的 AWS 区域：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
region = "us-west-2"

平台特定 URL ​

对于需要按平台分别下载的工具，请使用表格格式：

toml
[tools."s3:my-tool"]
version = "1.0.0"

[tools."s3:my-tool".platforms]
macos-x64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-macos-x64.tar.gz" }
macos-arm64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-macos-arm64.tar.gz" }
linux-x64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-linux-x64.tar.gz" }

checksum ​

使用校验和验证已下载的文件：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz"
checksum = "sha256:a1b2c3d4e5f6789..."

你也可以不在这里指定校验和，而是使用 mise.lock 来管理校验和。

size ​

验证已下载对象的大小：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz"
size = "12345678"

你可以为不同平台指定不同的大小：

toml
[tools."s3:my-tool"]
version = "1.0.0"

[tools."s3:my-tool".platforms]
macos-arm64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-macos-arm64.tar.gz", size = "9876543" }
linux-x64 = { url = "s3://my-bucket/tools/my-tool-v1.0.0-linux-x64.tar.gz", size = "12345678" }

strip_components ​

解压归档时要去除的目录组件数量：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz"
strip_components = 1

INFO

如果没有显式设置 strip_components，mise 会自动检测何时应用 strip_components = 1。当解压后的归档在根目录下恰好包含一个目录且不包含文件时，就会发生这种情况。

bin ​

将下载的二进制文件重命名为指定名称。当下载单个二进制对象且其名称包含平台特定后缀时，这很有用：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-linux-x86_64"
bin = "my-tool"

INFO

在下载单个二进制文件（非归档）时，mise 会自动从文件名中移除操作系统/架构后缀。例如，my-tool-linux-x86_64 会自动变为 my-tool。只有在你需要自定义名称时才使用 bin 选项。

rename_exe ​

在从归档中解压后重命名可执行文件。当归档中包含一个名称带有平台特定后缀、但你希望重命名的二进制文件时，这很有用：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0-linux.zip"
rename_exe = "my-tool"

TIP

对于归档中二进制文件名称与目标名称不同的情况，请使用 rename_exe。对于单个二进制文件下载（非归档），请使用 bin。

bin_path ​

指定解压后的归档中包含二进制文件的目录：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0.tar.gz"
bin_path = "my-tool-{{ version }}/bin"

format ​

当 URL 缺少文件扩展名时，显式指定归档格式：

toml
[tools."s3:my-tool"]
version = "1.0.0"
url = "s3://my-bucket/tools/my-tool-v1.0.0"
format = "tar.gz"

版本发现 ​

S3 后端支持两种发现可用版本的方法。

清单文件 ​

从存储在 S3 中的 JSON 清单文件获取可用版本：

toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/versions.json"

清单文件可以是一个版本字符串的 JSON 数组：

json
["1.0.0", "1.1.0", "2.0.0"]

或者是一个对象数组（使用 version_json_path 提取版本）：

json
[{ "version": "1.0.0" }, { "version": "1.1.0" }, { "version": "2.0.0" }]

version_json_path ​

使用类似 jq 的路径表达式从 JSON 响应中提取版本：

toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/releases.json"
version_json_path = ".[].version"

version_expr ​

使用 expr-lang 表达式提取版本，以实现复杂的版本提取逻辑：

toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_list_url = "s3://my-bucket/tools/versions.txt"
version_expr = 'split(body, "\n")'

该表达式接收响应正文作为 body 变量，并应返回一个版本字符串数组。

S3 对象列表 ​

通过列出 S3 存储桶中的对象来发现版本：

toml
[tools."s3:my-tool"]
version = "latest"
url = "s3://my-bucket/tools/my-tool-v{{ version }}.tar.gz"
version_prefix = "tools/my-tool-v"
version_regex = "my-tool-v([0-9.]+)"
  • version_prefix：用于列出对象的 S3 key 前缀
  • version_regex：用于从对象 key 中提取版本号的正则表达式（使用第一个捕获组）

自定义端点示例（MinIO） ​

以下是一个使用 MinIO 作为 S3 兼容后端的完整示例：

toml
[tools."s3:my-internal-tool"]
version = "latest"
url = "s3://tools-bucket/releases/my-tool-{{ version }}.tar.gz"
endpoint = "http://minio.internal:9000"
region = "us-east-1"
version_list_url = "s3://tools-bucket/releases/versions.json"
bin_path = "bin"

配合环境变量：

sh
export AWS_ACCESS_KEY_ID="minio-access-key"
export AWS_SECRET_ACCESS_KEY="minio-secret-key"
mise install

与 HTTP 后端的比较 ​

特性S3 后端HTTP 后端
身份验证AWS 凭证（环境变量、~/.aws/credentials、IAM）HTTP 认证头
版本发现S3 列表或清单文件HTTP 端点
自定义端点是（MinIO 等）不适用
使用场景私有/企业工具公共下载