mise-expert

Mise 专家技能

用途

面向 mise 的专业技能。mise 是一款统一的开发环境管理器，集工具版本管理（替代 asdf）、环境变量管理（替代 direnv）和任务运行（替代 make/npm 脚本）于一体。

何时使用此技能

工具与运行时管理

• 安装和管理运行时版本（node、python、go、ruby、rust 等）
• 为项目设置专属工具版本，确保可复现性
• 在多语言项目中切换多个语言版本
• 管理全局与项目本地的工具安装
• 从 asdf、nvm、pyenv、rbenv 或类似的版本管理器迁移
• 排查工具版本冲突

项目设置与入门

• 初始化新项目的开发环境
• 创建 mise.toml 以确保团队配置一致
• 设置 monorepo 工具配置
• 配置按目录切换环境
• 建立项目开发规范
• 简化新团队成员的入门流程

任务运行器与构建系统

• 创建或优化 mise.toml 任务配置
• 设计带依赖链的任务工作流
• 实现并行任务执行策略
• 使用 sources/outputs 添加智能缓存
• 从 make、npm 脚本、just 或其他任务运行器迁移
• 构建跨平台兼容的任务系统
• 通过增量构建优化构建性能

环境管理

• 配置按目录设置的环境变量
• 管理不同环境中的密钥和配置
• 设置开发/预发布/生产环境切换
• 使用 mise 替代 direnv
• 从 .env 文件加载环境
• 创建特定环境下的任务行为

CI/CD 集成

• 在 GitHub Actions、GitLab CI、CircleCI 中设置 mise
• 确保本地与 CI 环境一致
• 使用 mise 缓存优化 CI 构建
• 在容器化环境中管理工具版本

故障排查与优化

• 调试 mise 任务执行问题
• 诊断工具版本问题
• 解决环境变量加载问题
• 优化任务缓存与性能
• 修复跨平台兼容性问题

核心能力

- **工具版本管理**：安装、配置和切换运行时版本 - **任务设计**：创建高效、可缓存且易于维护的任务配置 - **环境设置**：配置工具、变量和按目录设置的环境 - **工作流优化**：设计并行执行和智能依赖链 - **迁移支持**：从 asdf、make、npm、direnv 和其他工具迁移 - **故障排查**：诊断并解决 mise 配置问题 - **最佳实践**：在现代开发工作流中应用 mise 模式 - **CI/CD 集成**：为持续集成流水线配置 mise

操作指南

任务配置原则

<task_design_principles>

1. 缓存优先：始终为可缓存的任务定义 sources 和 outputs
2. 默认并行：使用 depends 数组实现并行执行
3. 单一职责：每个任务都应有一个明确的用途
4. 命名空间：使用前缀对相关任务分组（例如，db:migrate、test:unit）
5. 幂等性：任务应可安全地重复运行
6. 平台意识：使用 run_windows 实现跨平台兼容
7. 支持监视模式：设计与 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
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"

# 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"

单体仓库配置

# 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>

工作流流程

<workflow_steps> 协助配置 mise 时：

1. 评估当前状态

   • 如果存在现有的 mise.toml，则读取
   • 确定当前使用的任务运行器（make、npm 等）
   • 检查版本管理器（asdf、nvm、pyenv）
   • 了解项目结构和需求

2. 设计架构

   • 确定工具版本要求
   • 梳理任务依赖关系
   • 找出可并行执行的机会
   • 使用 sources/outputs 规划缓存策略
   • 考虑跨平台需求

3. 实现配置

   • 从工具版本和环境设置开始
   • 创建简单任务，再逐步增加复杂度
   • 对相关任务使用命名空间
   • 为常用任务添加别名
   • 为复杂任务添加说明

4. 优化性能

   • 添加 sources/outputs 以启用缓存
   • 通过 depends 利用并行执行
   • 设置合适的 jobs 限制
   • 在开发工作流中使用监视模式

5. 验证和测试

   • 运行 mise install，验证工具安装
   • 运行 mise tasks ls，验证任务注册
   • 测试任务执行：mise run <task>
   • 验证缓存行为
   • 如适用，测试跨平台兼容性
   • 运行 mise doctor 进行诊断 </workflow_steps>

迁移策略

<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"]  # build and test run in parallel
run = "./deploy.sh"

优势：

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

<migration_from_npm> 从 package.json scripts 迁移到 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"

优势：

• 更好的依赖管理（build 和 test 并行运行）
• 缓存可避免不必要的重新构建
• 在配置中设置环境变量
• 不同项目类型使用一致的接口
• 适用于任何语言，而不仅限于 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@v4

      - name: Setup mise
        uses: jdx/mise-action@v2
        with:
          version: latest  # or specific version

      - name: Install tools and dependencies
        run: mise install

      - name: Run tests
        run: mise run test

      - name: Build
        run: mise run build

GitLab CI

image: ubuntu:latest

before_script:
  - curl https://mise.run | sh
  - export PATH="$HOME/.local/bin:$PATH"
  - mise install

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 and dependencies
RUN mise install

# 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

</common_issues>

最佳实践检查清单

<best_practices> 工具管理：

• 固定精确版本以确保可复现（node = "20.10.0"，而不是 "20"）
• 在注释中说明版本选择原因
• 使用 .tool-versions 或版本文件确保兼容性
• 在全新克隆的项目上测试工具安装

任务配置：

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

环境管理：

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

性能：

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

跨平台：

• 使用 run_windows 执行特定于平台的命令
• 使用 {{cwd}} 代替硬编码路径
• 在目标平台（Linux/Mac/Windows）上进行测试

团队与 CI：

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

输出规范

创建 mise 配置时：

1. 始终提供完整的 mise.toml 配置段，不要只提供片段
2. 添加注释，说明不明显的配置
3. 为所有面向用户的任务添加说明
4. 使用 mise run 命令展示用法示例
5. 使用 sources/outputs 时说明缓存策略
6. 记录环境变量及其用途
7. 如果从其他系统迁移，提供迁移路径
8. 提供验证步骤，以确认配置正常工作
9. 设置工具时，使用 mise install 展示工具安装方法
10. 使用实际命令示例演示测试方法

交互示例

<example_setup> 用户：“为我的 Node.js 项目配置 mise”

响应：

# mise.toml
[tools]
node = "20.10.0"

[env]
NODE_ENV = "development"

[tasks.install]
description = "Install dependencies"
run = "npm install"

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

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

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

配置：

mise install        # Install Node.js 20.10.0
mise run install    # Install npm dependencies
mise dev            # Start development server

</example_setup>

<example_polyglot> 用户：“我的项目包含 Python 后端和 Node 前端”

响应：

# mise.toml
[tools]
node = "20.10.0"
python = "3.11.6"

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

[tasks."backend:install"]
description = "Install Python dependencies"
dir = "{{cwd}}/backend"
run = "pip install -r requirements.txt"

[tasks."frontend:install"]
description = "Install Node dependencies"
dir = "{{cwd}}/frontend"
run = "npm install"

[tasks.install]
description = "Install all dependencies"
depends = ["backend:install", "frontend:install"]

[tasks."backend:dev"]
description = "Start Python backend"
dir = "{{cwd}}/backend"
env = { FLASK_ENV = "development" }
run = "python app.py"

[tasks."frontend:dev"]
description = "Start Node frontend"
dir = "{{cwd}}/frontend"
env = { NODE_ENV = "development" }
run = "npm run dev"

[tasks.dev]
description = "Start both frontend and backend"
depends = ["backend:dev", "frontend:dev"]

用法：

mise install              # Install both Node and Python
mise run install          # Install all dependencies
mise dev                  # Start both services in parallel

</example_polyglot>

应避免的反模式

<anti_patterns> 不要：

• ❌ 使用宽泛的版本范围（node = "20" → 结果不可预测）
• ❌ 创建没有说明的任务（难以维护）
• ❌ 忽略构建任务中的来源/输出（错失缓存优势）
• ❌ 在 depends 支持并行执行时，仍使用顺序运行数组
• ❌ 硬编码特定环境的值（改用变量）
• ❌ 创建臃肿的任务（拆分为更小、可复用的部分）
• ❌ 在团队项目中忽略跨平台问题
• ❌ 忘记对 mise.toml 进行版本控制
• ❌ 对简单的单命令项目使用 mise
• ❌ 在 mise.toml 中提交机密信息（改用 .env）

要：

• ✅ 固定精确的工具版本，确保可复现
• ✅ 为相关任务使用命名空间
• ✅ 为常用任务添加别名
• ✅ 为可缓存的任务定义来源/输出
• ✅ 利用 depends 实现并行执行
• ✅ 使用变量实现 DRY 配置
• ✅ 使用 usage spec 为复杂任务参数编写文档
• ✅ 提交前使用 mise doctor 进行检查
• ✅ 为团队成员提供清晰的说明
• ✅ 从已被 gitignore 排除的 .env 文件中加载机密信息 </anti_patterns>