mise-expert

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Mise Expert Skill

Mise 专家技能指南

Purpose

用途

Specialized skill for mise - a unified development environment manager combining tool version management (asdf replacement), environment variable management (direnv replacement), and task running (make/npm scripts replacement).
专门针对 mise 的技能——mise 是一款统一的开发环境管理器,整合了工具版本管理(替代 asdf)、环境变量管理(替代 direnv)和任务运行(替代 make/npm 脚本)功能。

When to Use This Skill

何时使用本技能

Tool & Runtime Management

工具与运行时管理

  • Installing and managing runtime versions (node, python, go, ruby, rust, etc.)
  • Setting up project-specific tool versions for reproducibility
  • Switching between multiple language versions in polyglot projects
  • Managing global vs project-local tool installations
  • Migrating from asdf, nvm, pyenv, rbenv, or similar version managers
  • Troubleshooting tool version conflicts
  • 安装和管理运行时版本(node、python、go、ruby、rust 等)
  • 为项目设置特定工具版本以确保可复现性
  • 在多语言项目中切换不同语言版本
  • 管理全局与项目本地的工具安装
  • 从 asdf、nvm、pyenv、rbenv 或类似版本管理器迁移
  • 排查工具版本冲突问题

Project Setup & Onboarding

项目搭建与新成员入职

  • Bootstrapping new project development environments
  • Creating mise.toml for team consistency
  • Setting up monorepo tool configurations
  • Configuring per-directory environment switching
  • Establishing project development standards
  • Simplifying onboarding for new team members
  • 快速搭建新项目的开发环境
  • 创建 mise.toml 以保证团队一致性
  • 配置 monorepo 的工具设置
  • 配置按目录切换的环境
  • 建立项目开发标准
  • 简化新团队成员的入职流程

Task Runner & Build Systems

任务运行器与构建系统

  • Creating or optimizing mise.toml task configurations
  • Designing task workflows with dependency chains
  • Implementing parallel task execution strategies
  • Adding intelligent caching with sources/outputs
  • Converting from make, npm scripts, just, or other task runners
  • Building cross-platform compatible task systems
  • Optimizing build performance with incremental builds
  • 创建或优化 mise.toml 任务配置
  • 设计带有依赖链的任务工作流
  • 实现并行任务执行策略
  • 通过 sources/outputs 添加智能缓存
  • 从 make、npm 脚本、just 或其他任务运行器迁移
  • 构建跨平台兼容的任务系统
  • 通过增量构建优化构建性能

Environment Management

环境管理

  • Configuring per-directory environment variables
  • Managing secrets and configuration across environments
  • Setting up development/staging/production environment switching
  • Replacing direnv with mise
  • Loading environment from .env files
  • Creating environment-specific task behaviors
  • 配置按目录划分的环境变量
  • 跨环境管理密钥和配置
  • 搭建开发/预发布/生产环境的切换机制
  • 使用 mise 替代 direnv
  • 从 .env 文件加载环境变量
  • 创建环境特定的任务行为

CI/CD Integration

CI/CD 集成

  • Setting up mise in GitHub Actions, GitLab CI, CircleCI
  • Ensuring consistent environments between local and CI
  • Optimizing CI builds with mise caching
  • Managing tool versions in containerized environments
  • 在 GitHub Actions、GitLab CI、CircleCI 中配置 mise
  • 确保本地与 CI 环境的一致性
  • 通过 mise 缓存优化 CI 构建
  • 在容器化环境中管理工具版本

Troubleshooting & Optimization

故障排查与优化

  • Debugging mise task execution issues
  • Diagnosing tool version problems
  • Resolving environment variable loading issues
  • Optimizing task caching and performance
  • Fixing cross-platform compatibility issues
  • 调试 mise 任务执行问题
  • 诊断工具版本问题
  • 解决环境变量加载问题
  • 优化任务缓存和性能
  • 修复跨平台兼容性问题

Core Capabilities

核心功能

<capabilities> - **Tool Version Management**: Install, configure, and switch between runtime versions - **Task Design**: Create efficient, cacheable, and maintainable task configurations - **Environment Setup**: Configure tools, variables, and per-directory environments - **Workflow Optimization**: Design parallel execution and intelligent dependency chains - **Migration Support**: Convert from asdf, make, npm, direnv, and other tools - **Troubleshooting**: Diagnose and resolve mise configuration issues - **Best Practices**: Apply mise patterns for modern development workflows - **CI/CD Integration**: Configure mise for continuous integration pipelines </capabilities>
<capabilities> - **工具版本管理**:安装、配置和切换运行时版本 - **任务设计**:创建高效、可缓存且易于维护的任务配置 - **环境搭建**:配置工具、变量和按目录划分的环境 - **工作流优化**:设计并行执行和智能依赖链 - **迁移支持**:从 asdf、make、npm、direnv 等工具迁移 - **故障排查**:诊断并解决 mise 配置问题 - **最佳实践**:将 mise 模式应用于现代开发工作流 - **CI/CD 集成**:为持续集成流水线配置 mise </capabilities>

Operational Guidelines

操作指南

Task Configuration Principles

任务配置原则

<task_design_principles>
  1. Caching First: Always define
    sources
    and
    outputs
    for cacheable tasks
  2. Parallel by Default: Use
    depends
    arrays for parallel execution
  3. Single Responsibility: Each task should have one clear purpose
  4. Namespacing: Group related tasks with prefixes (e.g.,
    db:migrate
    ,
    test:unit
    )
  5. Idempotency: Tasks should be safe to run multiple times
  6. Platform Awareness: Use
    run_windows
    for cross-platform compatibility
  7. Watch Mode Ready: Design tasks compatible with
    mise watch
    </task_design_principles>
<task_design_principles>
  1. 缓存优先:始终为可缓存任务定义
    sources
    outputs
  2. 默认并行:使用
    depends
    数组实现并行执行
  3. 单一职责:每个任务应只有一个明确的用途
  4. 命名空间:使用前缀对相关任务进行分组(如
    db:migrate
    test:unit
  5. 幂等性:任务可安全重复执行
  6. 平台感知:使用
    run_windows
    实现跨平台兼容
  7. 支持监听模式:设计兼容
    mise watch
    的任务 </task_design_principles>

Decision Framework

决策框架

<when_to_use_mise> Choose mise for:
  • Multi-language projects requiring version management (Python + Node + Go)
  • Projects needing per-directory environment variables
  • Cross-platform development teams (Linux/Mac/Windows)
  • Replacing complex Makefiles or npm scripts
  • Projects with parallel task execution needs
  • Teams wanting consistent dev environments (new dev onboarding)
  • Replacing multiple tools (asdf + direnv + make) with one
  • CI/CD pipelines requiring reproducible builds
Skip mise for:
  • Single-language projects with simple build steps
  • Projects where npm scripts are sufficient
  • Teams unfamiliar with TOML and no bandwidth for learning
  • Projects with existing, working task systems and no pain points
  • Embedded systems or constrained environments </when_to_use_mise>
<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 Version Management Patterns

工具版本管理模式

<tool_installation_patterns> Project-Specific Tools
toml
undefined
<tool_installation_patterns> 项目特定工具
toml
undefined

mise.toml - Project root configuration

mise.toml - 项目根目录配置

[tools]
[tools]

Exact versions for reproducibility

精确版本以保证可复现性

node = "20.10.0" python = "3.11.6" go = "1.21.5" terraform = "1.6.6"
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" }
ruby = { file = ".ruby-version" } java = { file = ".java-version" }

Latest patch version

最新补丁版本

postgres = "16" redis = "7"
postgres = "16" redis = "7"

Multiple versions (switch with mise use)

多版本(使用 mise use 切换)

mise use node@18 (temporarily override)

mise use node@18(临时覆盖)


**Global Development Tools**
```bash

**全局开发工具**
```bash

Install globally useful CLI tools

安装全局有用的 CLI 工具

mise use -g ripgrep@latest # Better grep mise use -g bat@latest # Better cat

**Version File Migration**
```bash
mise use -g ripgrep@latest # 增强版 grep mise use -g bat@latest # 增强版 cat

**版本文件迁移**
```bash

Migrate from existing version files

从现有版本文件迁移

echo "20.10.0" > .node-version echo "3.11.6" > .python-version
echo "20.10.0" > .node-version echo "3.11.6" > .python-version

mise.toml

mise.toml

[tools] node = { file = ".node-version" } python = { file = ".python-version" }
</tool_installation_patterns>
[tools] node = { file = ".node-version" } python = { file = ".python-version" }
</tool_installation_patterns>

Project Setup Workflows

项目搭建工作流

<project_setup_patterns> New Project Bootstrap
toml
undefined
<project_setup_patterns> 新项目快速搭建
toml
undefined

mise.toml

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 Configuration**
```toml
[tools] node = "20" python = "3.11"
[env] PROJECT_ROOT = "{{cwd}}" LOG_LEVEL = "debug"
[vars] project_name = "my-app"
[tasks.setup] description = "搭建开发环境" run = [ "mise install", "npm install", "pip install -r requirements.txt", "cp .env.example .env" ]
[tasks.dev] alias = "d" description = "启动开发服务器" depends = ["setup"] env = { NODE_ENV = "development" } run = "npm run dev"

**Monorepo 配置**
```toml

Root mise.toml

根目录 mise.toml

[tools] node = "20" go = "1.21"
[tasks.install] description = "Install all dependencies" run = [ "cd frontend && npm install", "cd backend && go mod download" ]
[tools] node = "20" go = "1.21"
[tasks.install] description = "安装所有依赖" run = [ "cd frontend && npm install", "cd backend && go mod download" ]

frontend/mise.toml

frontend/mise.toml

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

backend/mise.toml

backend/mise.toml

[tools] go = "1.21"
[tasks.dev] dir = "{{cwd}}/backend" run = "go run main.go"
</project_setup_patterns>
[tools] go = "1.21"
[tasks.dev] dir = "{{cwd}}/backend" run = "go run main.go"
</project_setup_patterns>

Configuration Patterns

配置模式

<common_patterns> Development Workflow
toml
[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"
Build Pipeline with Caching
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", "tsconfig.json"]
outputs = ["dist/**/*"]
env = { NODE_ENV = "production" }
run = "npm run build"

[tasks.build-watch]
description = "Rebuild on source changes"
run = "mise watch build"
Testing Suite
toml
[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"
Database Workflow
toml
[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"
Linting & Formatting
toml
[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
Deployment Pipeline
toml
[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 Integration
toml
[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 Plugin Build System
toml
[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>
<common_patterns> 开发工作流
toml
[tasks.dev]
alias = "d"
description = "启动带热重载的开发服务器"
env = { NODE_ENV = "development", DEBUG = "true" }
run = "npm run dev"

[tasks.dev-watch]
description = "监听文件变化并重新构建"
run = "mise watch build"
带缓存的构建流水线
toml
[tasks.clean]
description = "移除构建产物"
run = "rm -rf dist"

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

[tasks.build-watch]
description = "源文件变化时重新构建"
run = "mise watch build"
测试套件
toml
[tasks.test]
alias = "t"
description = "运行所有测试"
depends = ["test:unit", "test:integration"]  # 默认并行运行

[tasks."test:unit"]
description = "运行单元测试"
sources = ["src/**/*.ts", "tests/unit/**/*.ts"]
run = "npm test -- --testPathPattern=unit"

[tasks."test:integration"]
description = "运行集成测试"
sources = ["src/**/*.ts", "tests/integration/**/*.ts"]
run = "npm test -- --testPathPattern=integration"

[tasks."test:watch"]
description = "监听模式运行测试"
run = "npm test -- --watch"

[tasks."test:coverage"]
description = "生成覆盖率报告"
run = "npm test -- --coverage"

[tasks."test:e2e"]
description = "运行端到端测试"
depends = ["build"]
run = "playwright test"
数据库工作流
toml
[tasks."db:migrate"]
description = "运行数据库迁移"
run = "npx prisma migrate deploy"

[tasks."db:seed"]
description = "为数据库填充测试数据"
depends = ["db:migrate"]
run = "npx prisma db seed"

[tasks."db:reset"]
description = "将数据库重置为干净状态"
run = ["npx prisma migrate reset --force", "mise run db:seed"]

[tasks."db:studio"]
description = "打开 Prisma Studio"
run = "npx prisma studio"
代码检查与格式化
toml
[tasks.lint]
description = "代码检查"
sources = ["src/**/*.ts"]
run = "eslint src"

[tasks.format]
description = "代码格式化"
sources = ["src/**/*.ts"]
run = "prettier --write src"

[tasks."lint:fix"]
description = "代码检查并自动修复问题"
run = "eslint src --fix"

[tasks.check]
description = "运行所有检查"
depends = ["lint", "format", "test"]  # 并行运行
部署流水线
toml
[tasks.deploy]
description = "部署到生产环境"
usage = '''
arg "environment" description="目标环境" default="staging"
flag "-f --force" description="跳过确认"
'''
depends = ["build", "test"]
depends_post = ["notify:slack"]
run = './scripts/deploy.sh {{arg(name="environment")}} {{flag(name="force")}}'

[tasks."deploy:staging"]
description = "部署到预发布环境"
depends = ["build", "test"]
run = "./scripts/deploy.sh staging"

[tasks."deploy:production"]
description = "部署到生产环境"
depends = ["build", "test"]
run = "./scripts/deploy.sh production"

[tasks."notify:slack"]
hide = true
run = 'curl -X POST $SLACK_WEBHOOK -d "Deployment complete"'
Docker 集成
toml
[tasks."docker:build"]
description = "构建 Docker 镜像"
sources = ["Dockerfile", "src/**/*"]
run = "docker build -t myapp:latest ."

[tasks."docker:run"]
description = "运行 Docker 容器"
depends = ["docker:build"]
run = "docker run -p 3000:3000 myapp:latest"

[tasks."docker:compose"]
description = "使用 docker-compose 启动服务"
run = "docker-compose up -d"
Go 插件构建系统
toml
[tasks."build:plugins"]
description = "并行构建所有 Go 插件"
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 = "引擎变更时重新构建插件"
sources = ["engine/**/*.go"]
depends = ["build:engine"]
run = "mise run build:plugins"
</common_patterns>

Variables and Environment Management

变量与环境管理

<environment_patterns> Environment-Specific Variables
toml
[vars]
<environment_patterns> 环境特定变量
toml
[vars]

Default development values

默认开发环境值

api_url = "http://localhost:3000" db_host = "localhost" db_port = "5432" debug_mode = "true"
api_url = "http://localhost:3000" db_host = "localhost" db_port = "5432" debug_mode = "true"

Load additional vars from .env

从 .env 加载额外变量

_.file = ".env"
[env]
_.file = ".env"
[env]

Static environment variables

静态环境变量

NODE_ENV = "development" LOG_LEVEL = "debug"
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"

**Multi-Environment Setup**
```toml
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"

**多环境配置**
```toml

mise.toml (base development config)

mise.toml(基础开发配置)

[vars] environment = "development" api_url = "http://localhost:3000"
[env] NODE_ENV = "development"
[vars] environment = "development" api_url = "http://localhost:3000"
[env] NODE_ENV = "development"

mise.staging.toml

mise.staging.toml

[vars] environment = "staging" api_url = "https://api.staging.example.com"
[env] NODE_ENV = "staging"
[vars] environment = "staging" api_url = "https://api.staging.example.com"
[env] NODE_ENV = "staging"

mise.production.toml

mise.production.toml

[vars] environment = "production" api_url = "https://api.example.com" debug_mode = "false"
[env] NODE_ENV = "production"

**Secret Management**
```toml
[vars] environment = "production" api_url = "https://api.example.com" debug_mode = "false"
[env] NODE_ENV = "production"

**密钥管理**
```toml

mise.toml (checked into git)

mise.toml(已提交到 git)

[vars]
[vars]

Non-sensitive defaults

非敏感默认值

Load secrets from .env (gitignored)

从 .env 加载密钥(已加入 gitignore)

_.file = ".env"
[env]
_.file = ".env"
[env]

Reference secrets loaded from .env

引用从 .env 加载的密钥

API_KEY = "{{vars.api_key}}" DATABASE_PASSWORD = "{{vars.db_password}}"
API_KEY = "{{vars.api_key}}" DATABASE_PASSWORD = "{{vars.db_password}}"

.env (NOT in git)

.env(未提交到 git)

api_key=secret-key-here db_password=secret-password
</environment_patterns>
api_key=secret-key-here db_password=secret-password
</environment_patterns>

Workflow Process

工作流步骤

<workflow_steps> When helping with mise configurations:
  1. Assess Current State
    • Read existing mise.toml if present
    • Identify current task runner (make, npm, etc.)
    • Check for version managers (asdf, nvm, pyenv)
    • Understand project structure and requirements
  2. Design Architecture
    • Determine tool version requirements
    • Map out task dependencies and relationships
    • Identify parallel execution opportunities
    • Plan caching strategy with sources/outputs
    • Consider cross-platform needs
  3. Implement Configuration
    • Start with tool versions and environment setup
    • Create simple tasks, add complexity incrementally
    • Use namespacing for related tasks
    • Add aliases for frequently used tasks
    • Document complex tasks with descriptions
  4. Optimize Performance
    • Add sources/outputs for caching
    • Leverage parallel execution via depends
    • Set appropriate
      jobs
      limit
    • Use watch mode for development workflows
  5. Validate and Test
    • Run
      mise install
      to verify tool installation
    • Run
      mise tasks ls
      to verify task registration
    • Test task execution:
      mise run <task>
    • Verify caching behavior
    • Test cross-platform if applicable
    • Run
      mise doctor
      for diagnostics </workflow_steps>
<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 Strategies

迁移策略

<migration_from_asdf> From .tool-versions to mise.toml
.tool-versions:
nodejs 20.10.0
python 3.11.6
golang 1.21.5
terraform 1.6.6
mise.toml:
toml
[tools]
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"
Migration command:
bash
undefined
<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:
toml
[tools]
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"
迁移命令:
bash
undefined

Mise can read .tool-versions directly

Mise 可直接读取 .tool-versions

mise install
mise install

Or convert to mise.toml

或转换为 mise.toml

mise use node@20.10.0 python@3.11.6 go@1.21.5 terraform@1.6.6
</migration_from_asdf>

<migration_from_make>
**From Makefile to mise.toml**

Makefile:
```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:
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"
Advantages:
  • Automatic caching via sources/outputs
  • Parallel execution of independent tasks
  • Cross-platform compatibility
  • Environment variable management
  • Tool version management integrated </migration_from_make>
<migration_from_npm> From package.json scripts to mise.toml
package.json:
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:
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"
Advantages:
  • Better dependency management (build + test run in parallel)
  • Caching prevents unnecessary rebuilds
  • Environment variables in configuration
  • Consistent interface across different project types
  • Works with any language, not just Node.js </migration_from_npm>
<migration_from_direnv> From .envrc to mise.toml
.envrc:
bash
export NODE_ENV=development
export API_URL=http://localhost:3000
export DATABASE_URL=postgres://localhost/myapp
mise.toml:
toml
[env]
NODE_ENV = "development"
API_URL = "http://localhost:3000"
DATABASE_URL = "postgres://localhost/myapp"
mise use node@20.10.0 python@3.11.6 go@1.21.5 terraform@1.6.6
</migration_from_asdf>

<migration_from_make>
**从 Makefile 迁移到 mise.toml**

Makefile:
```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:
toml
[tasks.clean]
description = "移除构建产物"
run = "rm -rf dist"

[tasks.build]
alias = "b"
description = "构建生产包"
depends = ["clean"]
sources = ["src/**/*", "package.json"]
outputs = ["dist/**/*"]
run = "npm run build"

[tasks.test]
alias = "t"
description = "运行测试"
depends = ["build"]
run = "npm test"

[tasks.deploy]
description = "部署到生产环境"
depends = ["build", "test"]  # build 和 test 并行运行
run = "./deploy.sh"
优势:
  • 通过 sources/outputs 自动实现缓存
  • 独立任务并行执行
  • 跨平台兼容性
  • 环境变量管理
  • 集成工具版本管理 </migration_from_make>
<migration_from_npm> 从 package.json 脚本迁移到 mise.toml
package.json:
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:
toml
[tasks.dev]
alias = "d"
description = "启动开发服务器"
env = { NODE_ENV = "development" }
run = "npm start"

[tasks.build]
alias = "b"
description = "构建生产包"
sources = ["src/**/*", "webpack.config.js"]
outputs = ["dist/**/*"]
run = "webpack --mode production"

[tasks.test]
alias = "t"
description = "运行测试"
run = "jest"

[tasks.lint]
description = "代码检查"
sources = ["src/**/*.js"]
run = "eslint src"

[tasks.deploy]
description = "部署到生产环境"
depends = ["build", "test"]  # 并行运行
run = "./deploy.sh"
优势:
  • 更优的依赖管理(build + test 并行运行)
  • 缓存避免不必要的重新构建
  • 配置中统一管理环境变量
  • 不同项目类型的一致操作界面
  • 支持所有语言,不仅限于 Node.js </migration_from_npm>
<migration_from_direnv> 从 .envrc 迁移到 mise.toml
.envrc:
bash
export NODE_ENV=development
export API_URL=http://localhost:3000
export DATABASE_URL=postgres://localhost/myapp
mise.toml:
toml
[env]
NODE_ENV = "development"
API_URL = "http://localhost:3000"
DATABASE_URL = "postgres://localhost/myapp"

Or use variables for DRY

或使用变量实现 DRY

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

**Advantages:**
- TOML format easier to read/edit than bash
- Variables for DRY configuration
- Integrates with task runner and tool versions
- No shell-specific syntax
</migration_from_direnv>
[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 Integration

CI/CD 集成

<ci_integration> GitHub Actions
yaml
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
yaml
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
dockerfile
FROM ubuntu:latest
<ci_integration> GitHub Actions
yaml
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  # 或指定版本

      - name: Install tools and dependencies
        run: mise install

      - name: Run tests
        run: mise run test

      - name: Build
        run: mise run build
GitLab CI
yaml
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
dockerfile
FROM ubuntu:latest

Install mise

Install mise

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

Copy project files

Copy project files

COPY . /app WORKDIR /app
COPY . /app WORKDIR /app

Install tools and dependencies

Install tools and dependencies

RUN mise install
RUN mise install

Run build

Run build

RUN mise run build
CMD ["mise", "run", "start"]
</ci_integration>
RUN mise run build
CMD ["mise", "run", "start"]
</ci_integration>

Troubleshooting Guide

故障排查指南

<common_issues> Tool Not Found / Wrong Version
bash
undefined
<common_issues> 工具未找到 / 版本错误
bash
undefined

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

**Task Not Found**
```bash
mise ls # 列出已安装工具 mise install # 安装缺失工具 mise use node@20 # 设置特定版本 mise doctor # 诊断配置 which node # 验证 mise 垫片 mise reshim # 如有需要,重新构建垫片

**任务未找到**
```bash

Symptom: "Task 'xyz' not found"

症状:"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

**Task Caching Issues**
```toml
mise tasks ls # 列出所有任务 mise config # 显示当前配置文件位置 cat mise.toml # 验证任务定义 mise tasks info <task> # 获取任务详情

**任务缓存问题**
```toml

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"
[tasks.build] sources = ["src//*"] # 检查 glob 模式是否正确 outputs = ["dist//*"] # 验证输出路径与实际输出匹配 run = "npm run build"

Debug: Remove outputs and re-run

调试:移除输出并重新运行

rm -rf dist && mise run build

rm -rf dist && mise run build


**Environment Variables Not Loading**
```bash

**环境变量未加载**
```bash

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

**Cross-Platform Issues**
```toml
mise config # 验证 mise.toml 位置(项目根目录) mise run --verbose <task> # 通过详细输出检查环境加载 mise doctor # 诊断检查 env | grep VAR_NAME # 检查变量是否已设置

**跨平台问题**
```toml

Symptom: Task fails on Windows

症状:任务在 Windows 上失败

[tasks.build] run = "npm run build" # Use cross-platform commands run_windows = "npm.cmd run build" # Windows-specific override
[tasks.build] run = "npm run build" # 使用跨平台命令 run_windows = "npm.cmd run build" # Windows 特定覆盖

Or use mise variables for paths

或使用 mise 变量处理路径

run = "{{cwd}}/scripts/build.sh"

**Parallel Execution Not Working**
```toml
run = "{{cwd}}/scripts/build.sh"

**并行执行未生效**
```toml

Symptom: Tasks running sequentially instead of parallel

症状:任务顺序执行而非并行

[tasks.ci] depends = ["lint", "test", "build"] # Runs in parallel by default
[tasks.ci] depends = ["lint", "test", "build"] # 默认并行运行

For sequential execution, use run array

如需顺序执行,使用 run 数组

[tasks.sequential] run = [ "mise run step1", "mise run step2", "mise run step3" ]

**Tool Installation Fails**
```bash
[tasks.sequential] run = [ "mise run step1", "mise run step2", "mise run step3" ]

**工具安装失败**
```bash

Symptom: mise install fails for a tool

症状:mise install 安装工具失败

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>
mise doctor # 检查系统依赖 mise ls-remote node # 列出可用版本 mise install node@20 --verbose # 详细安装日志 mise cache clear # 清除缓存并重试
</common_issues>

Best Practices Checklist

最佳实践检查清单

<best_practices> Tool Management:
  • Pin exact versions for reproducibility (node = "20.10.0" not "20")
  • Document version choices in comments
  • Use .tool-versions or version files for compatibility
  • Test tool installation on fresh clone
Task Configuration:
  • All frequently used tasks have short aliases
  • Build tasks define sources and outputs for caching
  • Related tasks use namespace prefixes (db:, test:, docker:)
  • Complex tasks have clear descriptions
  • Tasks with arguments use usage spec for documentation
  • Hidden internal tasks marked with hide = true
Environment Management:
  • Environment variables use mise variables for DRY
  • Secrets loaded from .env (gitignored)
  • Development defaults in mise.toml (version controlled)
  • Production overrides in separate config files
Performance:
  • Parallel execution leveraged via depends arrays
  • Caching configured with sources/outputs
  • Watch mode available for iterative development
  • jobs setting optimized for system resources
Cross-Platform:
  • Platform-specific commands use run_windows
  • Paths use {{cwd}} instead of hardcoded values
  • Tested on target platforms (Linux/Mac/Windows)
Team & CI:
  • mise.toml version controlled
  • README documents mise installation and usage
  • CI/CD uses mise for consistent environments
  • Validated with
    mise doctor
    </best_practices>
<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 启用缓存
  • 为迭代开发提供监听模式
  • 根据系统资源优化 jobs 设置
跨平台:
  • 平台特定命令使用 run_windows
  • 路径使用 {{cwd}} 而非硬编码值
  • 在目标平台(Linux/Mac/Windows)上测试
团队与 CI:
  • mise.toml 已版本控制
  • README 文档中记录 mise 的安装和使用方法
  • CI/CD 使用 mise 保证环境一致性
  • 提交前使用
    mise doctor
    验证 </best_practices>

Output Standards

输出标准

When creating mise configurations:
  1. Always provide complete mise.toml sections, not fragments
  2. Include comments explaining non-obvious configurations
  3. Add descriptions to all user-facing tasks
  4. Show usage examples with
    mise run
    commands
  5. Explain caching strategy when using sources/outputs
  6. Document environment variables and their purposes
  7. Provide migration path if converting from other systems
  8. Include validation steps to verify configuration works
  9. Show tool installation with
    mise install
    when setting up tools
  10. Demonstrate testing with actual command examples
创建 mise 配置时:
  1. 始终提供完整的 mise.toml 片段,而非零散内容
  2. 添加注释解释非显而易见的配置
  3. 为所有面向用户的任务添加描述
  4. 提供使用示例,包括
    mise run
    命令
  5. 解释缓存策略(当使用 sources/outputs 时)
  6. 文档化环境变量及其用途
  7. 提供迁移路径(如果从其他系统转换)
  8. 包含验证步骤以确认配置可用
  9. 展示工具安装,设置工具时使用
    mise install
  10. 演示测试,提供实际命令示例

Example Interactions

示例交互

<example_setup> User: "Setup mise for my Node.js project"
Response:
toml
undefined
<example_setup> 用户:"为我的 Node.js 项目搭建 mise"
回复:
toml
undefined

mise.toml

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"

Setup:
```bash
mise install        # Install Node.js 20.10.0
mise run install    # Install npm dependencies
mise dev            # Start development server
</example_setup>
<example_polyglot> User: "I have a project with Python backend and Node frontend"
Response:
toml
undefined
[tools] node = "20.10.0"
[env] NODE_ENV = "development"
[tasks.install] description = "安装依赖" run = "npm install"
[tasks.dev] alias = "d" description = "启动开发服务器" env = { NODE_ENV = "development" } run = "npm run dev"
[tasks.build] alias = "b" description = "构建生产包" sources = ["src//*", "package.json"] outputs = ["dist//*"] env = { NODE_ENV = "production" } run = "npm run build"
[tasks.test] alias = "t" description = "运行测试" run = "npm test"

搭建步骤:
```bash
mise install        # 安装 Node.js 20.10.0
mise run install    # 安装 npm 依赖
mise dev            # 启动开发服务器
</example_setup>
<example_polyglot> 用户:"我有一个 Python 后端和 Node 前端的项目"
回复:
toml
undefined

mise.toml

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

Usage:
```bash
mise install              # Install both Node and Python
mise run install          # Install all dependencies
mise dev                  # Start both services in parallel
</example_polyglot>
[tools] node = "20.10.0" python = "3.11.6"
[env] PROJECT_ROOT = "{{cwd}}"
[tasks."backend:install"] description = "安装 Python 依赖" dir = "{{cwd}}/backend" run = "pip install -r requirements.txt"
[tasks."frontend:install"] description = "安装 Node 依赖" dir = "{{cwd}}/frontend" run = "npm install"
[tasks.install] description = "安装所有依赖" depends = ["backend:install", "frontend:install"]
[tasks."backend:dev"] description = "启动 Python 后端" dir = "{{cwd}}/backend" env = { FLASK_ENV = "development" } run = "python app.py"
[tasks."frontend:dev"] description = "启动 Node 前端" dir = "{{cwd}}/frontend" env = { NODE_ENV = "development" } run = "npm run dev"
[tasks.dev] description = "同时启动前端和后端" depends = ["backend:dev", "frontend:dev"]

使用方法:
```bash
mise install              # 同时安装 Node 和 Python
mise run install          # 安装所有依赖
mise dev                  # 并行启动两个服务
</example_polyglot>

Anti-Patterns to Avoid

需避免的反模式

<anti_patterns> Don't:
  • ❌ Use broad version ranges (node = "20" → unpredictable)
  • ❌ Create tasks without descriptions (hard to maintain)
  • ❌ Ignore sources/outputs on build tasks (misses caching benefits)
  • ❌ Use sequential run arrays when depends would allow parallel execution
  • ❌ Hardcode environment-specific values (use vars instead)
  • ❌ Create monolithic tasks (break into smaller, reusable pieces)
  • ❌ Skip cross-platform considerations for team projects
  • ❌ Forget to version control mise.toml
  • ❌ Use mise for trivial single-command projects
  • ❌ Commit secrets in mise.toml (use .env)
Do:
  • ✅ Pin exact tool versions for reproducibility
  • ✅ Use namespacing for related tasks
  • ✅ Add aliases for frequently used tasks
  • ✅ Define sources/outputs for cacheable tasks
  • ✅ Leverage parallel execution with depends
  • ✅ Use variables for DRY configuration
  • ✅ Document complex task arguments with usage spec
  • ✅ Test with
    mise doctor
    before committing
  • ✅ Provide clear descriptions for team members
  • ✅ Load secrets from gitignored .env files </anti_patterns>
<anti_patterns> 不要做这些:
  • ❌ 使用宽泛的版本范围(node = "20" → 不可预测)
  • ❌ 创建无描述的任务(难以维护)
  • ❌ 构建任务忽略 sources/outputs(错失缓存优势)
  • ❌ 当可以用 depends 实现并行时,却使用顺序 run 数组
  • ❌ 硬编码环境特定值(改用 vars)
  • ❌ 创建单体任务(拆分为更小的可复用模块)
  • ❌ 团队项目忽略跨平台考量
  • ❌ 忘记版本控制 mise.toml
  • ❌ 为简单单命令项目使用 mise
  • ❌ 在 mise.toml 中提交密钥(改用 .env)
应该做这些:
  • ✅ 固定精确的工具版本以保证可复现性
  • ✅ 对相关任务使用命名空间
  • ✅ 为常用任务添加别名
  • ✅ 为可缓存任务定义 sources/outputs
  • ✅ 通过 depends 利用并行执行
  • ✅ 使用变量实现 DRY 配置
  • ✅ 用 usage 规范文档化复杂任务的参数
  • ✅ 提交前用
    mise doctor
    测试
  • ✅ 为团队成员提供清晰的描述
  • ✅ 从已加入 gitignore 的 .env 文件加载密钥 </anti_patterns>