mise-expert

Name: mise-expert
Author: samhvw8

github.com/samhvw8开发15177 次安装今天更新

代码仓库

关于 mise-expert

mise-expert 是一项指导 Agent 处理 mise 问题的技能，重点是先核对实时文档与本机版本，再提供语法、设置或后端建议。内容涵盖工具后端、安全验证、信任配置及近期变更，并要求注明所依据的来源和版本。

主要功能

01优先核对已安装的 mise 与实时文档
02按变化频率区分文档内容
03解释工具安装后端的选择
04涵盖完整性验证与配置信任
05要求标注参考来源和版本

适用场景

01确认特定 mise 版本支持的命令或设置
02排查工具安装及后端选择问题
03核对签名或证明验证失败的原因
04处理配置文件信任与版本差异

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/samhvw8/dotfiles --skill mise-expert

安装后在 Claude Code 中输入/mise-expert确认已加载。

详细介绍

Mise 专家技能

首先检查实时文档

mise 每月发布多个版本，后端、设置、环境变量和标志都会随之变化。本文件是根据 mise 2026.10.11（2026-10-15） 发行说明和文档核对的快照，其中的设置和后端已通过 2026.10.10 版本的二进制文件确认；请把它当作查找信息的地图，而非当前事实。

在提供语法、设置名称、环境变量、标志或后端建议之前，请按以下顺序对照实时来源进行确认：

已安装的二进制文件 — mise --version、mise help <command>、mise settings ls、mise registry <tool>、mise doctor。这是此机器所运行版本的权威依据。
当前文档 — context7（解析 mise 库 ID，然后查询相关主题），或访问 https://mise.jdx.dev。如果 WebFetch 失败，请使用 mcp__parallax__fetch_page。
快照之后的变更 — 如果已安装的版本比上文所列版本更新，或用户遇到本文件未涵盖的行为，请查阅 https://github.com/jdx/mise/releases 上的发行说明。

本文件各部分需要进行此项检查的频率：

标签	章节	查询实时文档
易变	后端、安全验证、信任、证明和 `ubi` 故障排查条目、CI/CD 集成	每次都要
可能过时	新近功能、配置模式、变量和环境管理、迁移策略	引用确切键名或语法时
稳定	任务配置原则、决策框架、最佳实践检查清单、应避免的反模式	仅当用户报告不一致时

向用户说明你所依据的来源和版本（“依据 2026.10.11 版的 mise help use”“依据 mise.jdx.dev/configuration”）。如果只能使用本文件，请说明“来自技能的 2026.10.11 快照，未经实时核实”。如果实时来源与本文件矛盾，请以实时来源为准，并告知用户此技能已过时。

后端

mise 使用后端来安装工具。后端的选择会影响安全验证、性能和兼容性。

`mise backends ls` 会列出已安装二进制文件支持的后端。先查看注册表中的简称（`mise registry ` 会按顺序显示其后端列表）。自行选择后端时，文档中的顺序是：优先选择发布者自行签名或预构建的版本。

首选（预构建版本）

后端	语法	用途
core	`node`、`python`、`go`（`core:node`）	内置工具（node、python、bun、deno、java、go、rust、erlang 等）。
packslip	`packslip:github.com/owner/repo`（GitHub 仓库可用 `packslip:owner/repo`）	发布者签名的版本清单。mise 会检查签名者和每个制品的摘要。提供命令补全、man 页面和 Agent 技能。注册表已优先为 hk、usage、fnox、pitchfork、aube、helmfile、timoni、dagu、worktrunk 使用此后端。选项 `workflow = [...]` 用于固定签名工作流。
aqua	`aqua:owner/repo`	aqua 注册表中的工具。原生验证（cosign、SLSA、证明、minisign）。每个工具都可设置 `libc = "musl"` 选项。
github / gitlab / forgejo	`github:owner/repo`	Forge 版本资产。支持来源验证。已取代 ubi。
http / s3	`http:name` + `url`、`s3:name` + `url = "s3://..."`	由你托管的归档文件。`http` 使用 `headers` 进行身份验证；`s3` 使用 AWS 凭据链。

语言包（工具仅以包形式发布或需要包选项时）

后端	语法	用途
cargo	`cargo:crate`	来自 crates.io 的 Rust 工具。支持 cargo-binstall。
go	`go:module`	通过 `go install` 安装 Go 工具。
npm	`npm:package`、`npm:github:owner/repo@ref`	Node 包，也支持从 git 安装。支持 npm/pnpm/bun/aube。
pypi（别名为 `pipx:`）	`pypi:package`、`pypi:owner/repo`、`pypi:git+https://...#subdirectory=x`	在隔离环境中运行的 Python CLI 应用。使用 uv；若未安装 uv，则使用 pipx。若 mise 管理 Python，则会基于 mise 管理的 Python 构建。`pipx:x` 和 `pypi:x` 是同一个工具。
gem	`gem:package`	Ruby gem。私有注册表可使用 `source = "<url>"`。
dotnet	`dotnet:Package.Name`	来自 NuGet 的 .NET 工具。
spm	`spm:owner/repo`	Swift 包可执行文件。需要 Swift。
conda	`conda:package`	Conda 包及其依赖项。

插件及其他

后端	语法	用途
vfox	`vfox:owner/plugin`	Lua 插件，仅在安装需要自定义逻辑时使用。
spinel	`spinel:owner/repo`	实验性后端。将 Ruby 程序 AOT 编译为原生程序。需要设置 `experimental = true` 并使用 `spinel` 编译器。
asdf	`asdf:plugin`	旧版后端。会运行任意 shell 插件代码，不支持 Windows。新工具请勿使用。

已弃用

后端	替代方案	迁移
ubi	github / gitlab / http	自 2026.4.0 起发出警告，将在 mise 2027.1.0 中移除。`ubi:owner/repo` → `github:owner/repo`；`provider = "gitlab"` → `gitlab:`；直接 URL → 带 `url` 的 `http:`。通常不需要 `exe`；`rename_exe` 应改为 `rename_exe = { "gh" = "gh-cli" }`。然后运行 `mise lock` 和 `mise uninstall --all ubi:owner/repo`。

简称的解析顺序（显式的 backend: 前缀始终优先）：MISE_BACKENDS_<TOOL> 环境变量 → 指定后端的 [tool_alias] 条目（例如 node = "core:node"）→ [plugins] URL → mise.lock 中记录的后端（若其提供所需版本）→ 同名的已安装插件 → 此处可运行、未列入 disable_backends 且提供所需版本的第一个注册表后端。使用 mise tool <name> --backend 查看。注册表更改工具的后端时，mise backends switch 会迁移锁定条目。

推荐优先级：core > packslip > aqua > github/gitlab/forgejo > http/s3 > 语言包（cargo/go/npm/pypi/gem/dotnet）> vfox > asdf

后端覆盖示例：

[tools]
# Default (registry decides backend — usually aqua)
uv = "latest"

# Explicit backend
"aqua:astral-sh/uv" = "latest"
"github:astral-sh/uv" = "latest"

# CLI override
mise use "github:astral-sh/uv@latest"

## 安全验证

aqua 后端通过原生 Rust 实现验证工具完整性，无需外部 CLI 工具（cosign、slsa-verifier、minisign、gh）。默认启用所有方法。

<security_verification> 验证方法

方法	环境变量	设置键	默认值
Cosign 签名	`MISE_AQUA_COSIGN`	`aqua.cosign`	true
SLSA 来源证明	`MISE_AQUA_SLSA`	`aqua.slsa`	true
GitHub 证明	`MISE_AQUA_GITHUB_ATTESTATIONS`	`aqua.github_attestations`	true
Minisign	`MISE_AQUA_MINISIGN`	`aqua.minisign`	true
校验和	始终开启	N/A	始终

适用于所有后端的全局开关：MISE_GITHUB_ATTESTATIONS=0（设置 github_attestations）。github 后端有自己的 github.github_attestations。

额外的 cosign 参数：MISE_AQUA_COSIGN_EXTRA_ARGS="--key /path/to/key.pub"

现已强制验证签署者身份（2026.9.16 – 2026.10.0）

SLSA 来源证明必须来自预期的签署者。对于注册表条目中未提供相关信息的 github: 和 aqua: 工具（例如 aqua:google/osv-scanner），请将 slsa_signer_identity 和 slsa_signer_issuer 设为工具选项。若未同时设置这两项，mise 会跳过 SLSA 检查并使用其他方法。
无密钥 cosign bundle 必须与注册表固定的 --certificate-identity/--certificate-oidc-issuer 匹配。基于密钥的方式（--key）不变。
GitHub 证明中的 signer_workflow 按完整路径段匹配，而非按子字符串匹配。

发行版本时间限制：minimum_release_age（默认值为 24h）会延迟工具的新发行版本和 mise self-update。如需立即获取最新版本，可对单个工具设置 --tool-option minimum_release_age=0s。minimum_release_age_excludes 用于列出豁免工具。

证明验证失败时

常见原因：发行版本由人工手动发布，未通过 GH Actions（因此没有生成证明）；sigstore 库不兼容；GitHub API 格式发生变化。

# Fix 1: Update mise first (many attestation bugs fixed in newer releases)
mise self-update

# Fix 2: Disable only the failing method
export MISE_AQUA_GITHUB_ATTESTATIONS=false
mise install <tool>@<version>

# Fix 3: Settings-based (persistent)
# In mise.toml or ~/.config/mise/config.toml
[settings]
aqua.github_attestations = false

# Fix 4: Debug to identify which method fails
MISE_DEBUG=1 mise install <tool>@<version>

**已知的单个工具证明问题：**某些发行版本由人工手动发布或早于 GitHub 证明支持，因此不包含证明——请安装相邻版本，或查看该工具的 aqua-registry 条目，了解是否有针对特定版本的豁免。 </security_verification>

信任

mise 会跳过或拒绝加载不受信任的配置。以下形式现在需要先运行 mise trust，才能加载：

带内联选项的工具键（"github:o/r[api_url=...]"），包括 mise.toml 和 .tool-versions 中的配置——不受信任的文件可能会将 GITHUB_TOKEN 发送到其他主机。
path: 工具版本——它们会将某个目录置于 PATH 的首位。
{ ... } 选项表、Tera 模板，以及 #MISE 标头中包含模板的远程任务文件。

node = "24" 这类普通键仍会在不受信任的情况下加载。不受信任的项目配置不再会导致 mise activate 失败：mise 会跳过该配置并发出警告，而 mise run 和 mise x 仍会报错。偏执模式：--yes/CI 自动确认不会授予信任。MISE_SAFE=1 会忽略项目的 [bootstrap]、[dotfiles] 和 include。

操作指南

任务配置原则

<task_design_principles>

优先考虑缓存：始终为可缓存任务定义 sources 和 outputs
默认并行执行：使用 depends 数组并行执行
单一职责：每个任务都应有一个明确的用途
命名空间：使用前缀对相关任务分组（例如，db:migrate、test:unit）
幂等性：任务应可安全地重复运行
平台适配：使用 run_windows 实现跨平台兼容
支持监视模式：设计与 mise watch 兼容的任务 </task_design_principles>

决策框架

<when_to_use_mise> 适合选择 mise 的情况：

需要管理多个语言版本的项目（Python + Node + Go）
需要按目录设置环境变量的项目
跨平台开发团队（Linux/Mac/Windows）
希望替代复杂的 Makefile 或 npm 脚本
需要并行执行任务的项目
希望保持开发环境一致的团队（便于新开发者入职）
希望用一个工具替代多种工具（asdf + direnv + make）
需要可复现构建的 CI/CD 流水线

不适合选择 mise 的情况：

构建步骤简单的单语言项目
npm 脚本已足够的项目
团队不熟悉 TOML，且没有时间学习
已有可正常使用的任务系统，且没有痛点的项目
嵌入式系统或受限环境 </when_to_use_mise>

工具版本管理模式

<tool_installation_patterns> 项目专用工具

# mise.toml - Project root configuration
[tools]
# Exact versions for reproducibility (illustrative — look up current ones with `mise latest <tool>`)
node = "<x.y.z>"
python = "<x.y.z>"
go = "<x.y.z>"
terraform = "<x.y.z>"

# Read from version file
ruby = { file = ".ruby-version" }
java = { file = ".java-version" }

# Latest patch version
postgres = "16"
redis = "7"

# Multiple versions (switch with mise use)
# mise use node@18 (temporarily override)

全局开发工具

# Install globally useful CLI tools
mise use -g ripgrep@latest      # Better grep
mise use -g bat@latest          # Better cat

版本文件迁移

# Migrate from existing version files
echo "20.10.0" > .node-version
echo "3.11.6" > .python-version

# mise.toml
[tools]
node = { file = ".node-version" }
python = { file = ".python-version" }

</tool_installation_patterns>

项目设置工作流

<project_setup_patterns> 新项目初始化

# mise.toml
[tools]
node = "20"
python = "3.11"

[env]
PROJECT_ROOT = "{{cwd}}"
LOG_LEVEL = "debug"

[vars]
project_name = "my-app"

[tasks.setup]
description = "Setup development environment"
run = [
  "mise install",
  "npm install",
  "pip install -r requirements.txt",
  "cp .env.example .env"
]

[tasks.dev]
alias = "d"
description = "Start development server"
depends = ["setup"]
env = { NODE_ENV = "development" }
run = "npm run dev"

Monorepo 配置

# Root mise.toml
[tools]
node = "20"
go = "1.21"

[tasks.install]
description = "Install all dependencies"
run = [
  "cd frontend && npm install",
  "cd backend && go mod download"
]

# frontend/mise.toml
[tasks.dev]
dir = "{{cwd}}/frontend"
run = "npm run dev"

# backend/mise.toml
[tools]
go = "1.21"

[tasks.dev]
dir = "{{cwd}}/backend"
run = "go run main.go"

</project_setup_patterns>

配置模式

<common_patterns> 开发工作流

[tasks.dev]
alias = "d"
description = "Start development server with hot reload"
env = { NODE_ENV = "development", DEBUG = "true" }
run = "npm run dev"

[tasks.dev-watch]
description = "Watch and rebuild on changes"
run = "mise watch build"

带缓存的构建流水线

[tasks.clean]
description = "Remove build artifacts"
run = "rm -rf dist"

[tasks.build]
alias = "b"
description = "Build production bundle"
depends = ["clean"]
sources = ["src/**/*", "package.json", "tsconfig.json"]
outputs = ["dist/**/*"]
env = { NODE_ENV = "production" }
run = "npm run build"

[tasks.build-watch]
description = "Rebuild on source changes"
run = "mise watch build"

测试套件

[tasks.test]
alias = "t"
description = "Run all tests"
depends = ["test:unit", "test:integration"]  # Runs in parallel

[tasks."test:unit"]
description = "Run unit tests"
sources = ["src/**/*.ts", "tests/unit/**/*.ts"]
run = "npm test -- --testPathPattern=unit"

[tasks."test:integration"]
description = "Run integration tests"
sources = ["src/**/*.ts", "tests/integration/**/*.ts"]
run = "npm test -- --testPathPattern=integration"

[tasks."test:watch"]
description = "Run tests in watch mode"
run = "npm test -- --watch"

[tasks."test:coverage"]
description = "Generate coverage report"
run = "npm test -- --coverage"

[tasks."test:e2e"]
description = "Run end-to-end tests"
depends = ["build"]
run = "playwright test"

数据库工作流

[tasks."db:migrate"]
description = "Run database migrations"
run = "npx prisma migrate deploy"

[tasks."db:seed"]
description = "Seed database with test data"
depends = ["db:migrate"]
run = "npx prisma db seed"

[tasks."db:reset"]
description = "Reset database to clean state"
run = ["npx prisma migrate reset --force", "mise run db:seed"]

[tasks."db:studio"]
description = "Open Prisma Studio"
run = "npx prisma studio"

代码检查与格式化

[tasks.lint]
description = "Lint code"
sources = ["src/**/*.ts"]
run = "eslint src"

[tasks.format]
description = "Format code"
sources = ["src/**/*.ts"]
run = "prettier --write src"

[tasks."lint:fix"]
description = "Lint and auto-fix issues"
run = "eslint src --fix"

[tasks.check]
description = "Run all checks"
depends = ["lint", "format", "test"]  # Runs in parallel

部署流水线

[tasks.deploy]
description = "Deploy to production"
usage = '''
arg "environment" description="Target environment" default="staging"
flag "-f --force" description="Skip confirmation"
'''
depends = ["build", "test"]
depends_post = ["notify:slack"]
run = './scripts/deploy.sh {{arg(name="environment")}} {{flag(name="force")}}'

[tasks."deploy:staging"]
description = "Deploy to staging"
depends = ["build", "test"]
run = "./scripts/deploy.sh staging"

[tasks."deploy:production"]
description = "Deploy to production"
depends = ["build", "test"]
run = "./scripts/deploy.sh production"

[tasks."notify:slack"]
hide = true
run = 'curl -X POST $SLACK_WEBHOOK -d "Deployment complete"'

Docker 集成

[tasks."docker:build"]
description = "Build Docker image"
sources = ["Dockerfile", "src/**/*"]
run = "docker build -t myapp:latest ."

[tasks."docker:run"]
description = "Run Docker container"
depends = ["docker:build"]
run = "docker run -p 3000:3000 myapp:latest"

[tasks."docker:compose"]
description = "Start services with docker-compose"
run = "docker-compose up -d"

Go 插件构建系统

[tasks."build:plugins"]
description = "Build all Go plugins in parallel"
sources = ["plugins/**/*.go"]
outputs = ["plugins/**/main.so"]
run = '''
for plugin in plugins/*/; do
  (cd "$plugin" && go build -buildmode=plugin -o main.so main.go) &
done
wait
'''

[tasks."rebuild:plugins"]
description = "Rebuild plugins when engine changes"
sources = ["engine/**/*.go"]
depends = ["build:engine"]
run = "mise run build:plugins"

</common_patterns>

变量与环境管理

<environment_patterns> 特定环境变量

[vars]
# Default development values
api_url = "http://localhost:3000"
db_host = "localhost"
db_port = "5432"
debug_mode = "true"

# Load additional vars from .env
_.file = ".env"

[env]
# Static environment variables
NODE_ENV = "development"
LOG_LEVEL = "debug"

# Reference variables
API_URL = "{{vars.api_url}}"
DATABASE_URL = "postgres://{{vars.db_host}}:{{vars.db_port}}/myapp"
DEBUG = "{{vars.debug_mode}}"

[tasks.dev]
env = {
  NODE_ENV = "development",
  API_URL = "{{vars.api_url}}"
}
run = "npm run dev"

多环境设置

# mise.toml (base development config)
[vars]
environment = "development"
api_url = "http://localhost:3000"

[env]
NODE_ENV = "development"

# mise.staging.toml
[vars]
environment = "staging"
api_url = "https://api.staging.example.com"

[env]
NODE_ENV = "staging"

# mise.production.toml
[vars]
environment = "production"
api_url = "https://api.example.com"
debug_mode = "false"

[env]
NODE_ENV = "production"

密钥管理

# mise.toml (checked into git)
[vars]
# Non-sensitive defaults
api_url = "http://localhost:3000"

# Load secrets from .env (gitignored)
_.file = ".env"

[env]
# Reference secrets loaded from .env
API_KEY = "{{vars.api_key}}"
DATABASE_PASSWORD = "{{vars.db_password}}"

# .env (NOT in git)
api_key=secret-key-here
db_password=secret-password

</environment_patterns>

验证配置

更改 mise 配置后，请进行检查：运行 mise install（解析工具）、mise tasks ls（注册任务）、mise run <task>（运行任务），并运行 mise doctor 进行诊断。

迁移策略

<migration_from_asdf> 从 .tool-versions 迁移到 mise.toml

.tool-versions：

nodejs 20.10.0
python 3.11.6
golang 1.21.5
terraform 1.6.6

mise.toml：

[tools]
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"

迁移命令：

# Mise can read .tool-versions directly
mise install

# Or convert to mise.toml
mise use [email protected] [email protected] [email protected] [email protected]

</migration_from_asdf>

<migration_from_make> 从 Makefile 迁移到 mise.toml

Makefile：

.PHONY: build test clean deploy

clean:
	rm -rf dist

build: clean
	npm run build

test: build
	npm test

deploy: build test
	./deploy.sh

mise.toml：

[tasks.clean]
description = "Remove build artifacts"
run = "rm -rf dist"

[tasks.build]
alias = "b"
description = "Build production bundle"
depends = ["clean"]
sources = ["src/**/*", "package.json"]
outputs = ["dist/**/*"]
run = "npm run build"

[tasks.test]
alias = "t"
description = "Run tests"
depends = ["build"]
run = "npm test"

[tasks.deploy]
description = "Deploy to production"
depends = ["build", "test"]  # test already depends on build, so these run in order
run = "./deploy.sh"

优点：

通过 sources/outputs 自动缓存
并行执行互不依赖的任务
跨平台兼容
环境变量管理
集成工具版本管理 </migration_from_make>

<migration_from_npm> 从 package.json 脚本迁移到 mise.toml

package.json：

{
  "scripts": {
    "dev": "NODE_ENV=development npm start",
    "build": "webpack --mode production",
    "test": "jest",
    "lint": "eslint src",
    "deploy": "npm run build && npm run test && ./deploy.sh"
  }
}

mise.toml：

[tasks.dev]
alias = "d"
description = "Start development server"
env = { NODE_ENV = "development" }
run = "npm start"

[tasks.build]
alias = "b"
description = "Build production bundle"
sources = ["src/**/*", "webpack.config.js"]
outputs = ["dist/**/*"]
run = "webpack --mode production"

[tasks.test]
alias = "t"
description = "Run tests"
run = "jest"

[tasks.lint]
description = "Lint code"
sources = ["src/**/*.js"]
run = "eslint src"

[tasks.deploy]
description = "Deploy to production"
depends = ["build", "test"]  # Runs in parallel
run = "./deploy.sh"

优点：

更好的依赖管理（并行运行构建和测试）
缓存可避免不必要的重新构建
在配置中管理环境变量
不同类型的项目使用一致的接口
适用于任何语言，而不仅限于 Node.js </migration_from_npm>

<migration_from_direnv> 从 .envrc 迁移到 mise.toml

.envrc：

export NODE_ENV=development
export API_URL=http://localhost:3000
export DATABASE_URL=postgres://localhost/myapp

mise.toml：

[env]
NODE_ENV = "development"
API_URL = "http://localhost:3000"
DATABASE_URL = "postgres://localhost/myapp"

# Or use variables for DRY
[vars]
api_host = "localhost"
api_port = "3000"

[env]
API_URL = "http://{{vars.api_host}}:{{vars.api_port}}"

优点：

TOML 格式比 bash 更易阅读和编辑
使用变量实现 DRY 配置
与任务运行器和工具版本集成
无需特定于 shell 的语法 </migration_from_direnv>

CI/CD 集成

<ci_integration> GitHub Actions

name: CI
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7

      # Installs mise and the repo's tools. With a committed mise.lock it runs
      # `mise install --locked` itself. Pin mise with `version:` if needed.
      - uses: jdx/mise-action@v5

      - name: Run tests
        run: mise run test

      - name: Build
        run: mise run build

mise-action v5 不会将 GitHub token 导出到后续步骤。请将 token 传递给安装工具的步骤。mise generate github-action --write --task=ci 会生成一个工作流模板。

缓存下载内容，而非安装结果（需提交 mise.lock）。mise 会根据锁文件重新计算每个缓存下载内容的哈希值，因此被污染的缓存无法更改安装内容。恢复的安装缓存则会直接信任。

      - uses: actions/checkout@v7
      - uses: actions/cache@v6
        with:
          path: ~/.cache/mise/downloads-cas   # macOS: ~/Library/Caches/mise/downloads-cas
          key: mise-downloads-${{ runner.os }}-${{ hashFiles('mise.lock') }}
      - uses: jdx/mise-action@v5
        with:
          cache: false

GitLab CI

image: ubuntu:latest

before_script:
  - curl https://mise.run | sh            # set MISE_VERSION=<x> for a reproducible mise
  - export PATH="$HOME/.local/bin:$PATH"
  - mise install --locked

test:
  script:
    - mise run test

build:
  script:
    - mise run build

Docker

FROM ubuntu:latest

# Install mise
RUN curl https://mise.run | sh
ENV PATH="/root/.local/bin:$PATH"

# Copy project files
COPY . /app
WORKDIR /app

# Install tools from the committed lockfile
RUN mise install --locked

# Run build
RUN mise run build

CMD ["mise", "run", "start"]

</ci_integration>

故障排除指南

<common_issues> 找不到工具 / 版本错误

# Symptom: Command not found or using system version
mise ls                          # List installed tools
mise install                     # Install missing tools
mise use node@20                 # Set specific version
mise doctor                      # Diagnose configuration
which node                       # Verify mise shim
mise reshim                      # Rebuild shims if needed

找不到任务

# Symptom: "Task 'xyz' not found"
mise tasks ls                    # List all tasks
mise config                      # Show active config files
cat mise.toml                    # Verify task definition
mise tasks info <task>           # Get task details

任务缓存问题

# Symptom: Task not re-running when files change
[tasks.build]
sources = ["src/**/*"]           # Check glob patterns are correct
outputs = ["dist/**/*"]          # Verify output paths match actual outputs
run = "npm run build"

# Debug: Remove outputs and re-run
# rm -rf dist && mise run build

环境变量未加载

# Symptom: Environment variables not set in tasks
mise config                      # Verify mise.toml location (project root)
mise run --verbose <task>        # Check env loading with verbose output
mise doctor                      # Diagnostic check
env | grep VAR_NAME              # Check if var is actually set

跨平台问题

# Symptom: Task fails on Windows
[tasks.build]
run = "npm run build"            # Use cross-platform commands
run_windows = "npm.cmd run build"  # Windows-specific override

# Or use mise variables for paths
run = "{{cwd}}/scripts/build.sh"

并行执行无法正常工作

# Symptom: Tasks running sequentially instead of parallel
[tasks.ci]
depends = ["lint", "test", "build"]  # Runs in parallel by default

# For sequential execution, use run array
[tasks.sequential]
run = [
  "mise run step1",
  "mise run step2",
  "mise run step3"
]

工具安装失败

# Symptom: mise install fails for a tool
mise doctor                      # Check for system dependencies
mise ls-remote node              # List available versions
mise install node@20 --verbose   # Verbose installation
mise cache clear                 # Clear cache and retry

证明 / 验证失败

# Symptom: "GitHub artifact attestations verification failed"
# or "Workflow verification failed: expected '...', found certificate: None"

# Step 1: Update mise (most attestation bugs are fixed in newer releases)
mise self-update

# Step 2: If still failing, disable ONLY the method Step 5's debug output names — one of:
export MISE_AQUA_GITHUB_ATTESTATIONS=false   # GitHub attestations
# export MISE_AQUA_COSIGN=false              # Cosign signatures
# export MISE_AQUA_SLSA=false                # SLSA provenance

# Step 3: Try an adjacent version (some releases lack attestations)
mise install <tool>@<other-version>

# Step 4: Switch backend as workaround
mise use "github:owner/repo@version"         # github backend instead of aqua

# Step 5: Debug for details
MISE_DEBUG=1 mise install tool@version

SLSA「no signer_identity and signer_issuer」

# Symptom: a locked or SLSA-checked aqua/github tool fails with no expected signer.
# Fix: refresh the entry with `mise lock`, or set both signer options:
[tools]
"aqua:google/osv-scanner" = { version = "latest", slsa_signer_identity = "<cert URI>", slsa_signer_issuer = "https://token.actions.githubusercontent.com" }

曾经可以加载的配置现在显示「is not trusted」

# Symptom: inline tool options ("tool[opt=x]") or path: versions are skipped.
mise trust            # in the project directory, after reading the file

使用已弃用的 ubi 后端

# Symptom: ubi backend warnings or failures (ubi is removed in 2027.1.0)
# Fix: Replace ubi with github backend
# Old: ubi:owner/repo → New: github:owner/repo

# In mise.toml
# Before (deprecated):
# "ubi:goreleaser/goreleaser" = "latest"
# After (recommended):
# "github:goreleaser/goreleaser" = "latest"

</common_issues>

最佳实践清单

<best_practices> 工具管理：

在共享项目和 CI 项目中固定精确版本；对于个人工具，主版本前缀（node = "22"）即可
在注释中说明版本选择
使用 .tool-versions 或版本文件确保兼容性
在全新克隆的项目中测试工具安装

任务配置：

为所有常用任务设置简短别名
为构建任务定义 sources 和 outputs，以启用缓存
相关任务使用命名空间前缀（db:、test:、docker:）
为复杂任务添加清晰的描述
使用参数的任务通过 usage spec 编写文档
将隐藏的内部任务标记为 hide = true

环境管理：

使用 mise 变量管理环境变量，避免重复
从 .env 加载密钥（已加入 gitignore）
在 mise.toml 中设置开发环境默认值（纳入版本控制）
在单独的配置文件中设置生产环境覆盖值

性能：

通过 depends 数组利用并行执行
使用 sources/outputs 配置缓存
提供监视模式以支持迭代开发
根据系统资源优化 jobs 设置

跨平台：

平台专属命令使用 run_windows
使用 {{cwd}} 代替硬编码路径
在目标平台（Linux/Mac/Windows）上测试

团队与 CI：

将 mise.toml 纳入版本控制
在 README 中说明 mise 的安装和使用方法
在 CI/CD 中使用 mise，以确保环境一致
使用 mise doctor 进行验证 </best_practices>

输出规范

编辑现有 mise.toml 时，只修改请求涉及的部分。面向用户的任务应提供 description，仅为不明显的配置添加注释。

应避免的反模式

<anti_patterns> 不要：

❌ 在共享项目或 CI 项目中使用宽泛的版本范围（node = "22" 会导致不同机器上的版本不一致）
❌ 创建没有描述的任务（难以维护）
❌ 忽略构建任务中的 sources/outputs（会错过缓存带来的好处）
❌ 在 depends 可以支持并行执行时，使用顺序执行的 run 数组
❌ 硬编码特定环境的值（改用 vars）
❌ 创建庞大的单体任务（拆分成更小、可复用的部分）
❌ 在团队项目中忽略跨平台因素
❌ 忘记对 mise.toml 进行版本控制
❌ 在只有一个简单命令的项目中使用 mise
❌ 在 mise.toml 中提交密钥（改用 .env）
❌ 使用 ubi: 后端（已弃用，改用 github:）
❌ 使用 MISE_AQUA_REGISTRY_COSIGN（环境变量错误，改用 MISE_AQUA_COSIGN）
❌ 仅当一种验证方法失败时，就全局禁用所有验证
❌ 在存在锁文件时，于 CI 中缓存已安装的工具（应缓存 downloads-cas）
❌ 对尚未阅读的仓库运行 mise trust——现在信任机制会约束 path: 版本和内联工具选项

要：

✅ 固定精确的工具版本，以确保可复现
✅ 使用命名空间组织相关任务
✅ 为常用任务添加别名
✅ 为可缓存的任务定义 sources/outputs
✅ 使用 depends 充分利用并行执行
✅ 使用变量实现 DRY 配置
✅ 使用 usage spec 记录复杂任务参数
✅ 在提交前使用 mise doctor 进行测试
✅ 为团队成员提供清晰的描述
✅ 从已被 Git 忽略的 .env 文件中加载密钥
✅ 对 GitHub Release 工具，优先使用 github: 而非 ubi:
✅ 在排查证明失败问题前运行 mise self-update
✅ 仅禁用具体失败的验证方法，而非全部验证方法
✅ 提交 mise.lock，并在 CI 和 Docker 中使用 --locked 安装
✅ 当发布者对 packslip 清单签名时，优先使用 packslip: </anti_patterns>

支持 Markdown

登录后评论

基本信息

作者: samhvw8
仓库: samhvw8/dotfiles
分类: 开发
安装次数: 177
GitHub Stars: 15

报告问题

mise-expert

关于 mise-expert

主要功能

适用场景

安装

详细介绍

Mise 专家技能

首先检查实时文档

后端

信任

最新功能

操作指南

任务配置原则

决策框架

工具版本管理模式

项目设置工作流

配置模式

变量与环境管理

验证配置

迁移策略

CI/CD 集成

故障排除指南

最佳实践清单

输出规范

应避免的反模式

评论