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

安装 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 . /app WORKDIR /app
COPY . /app WORKDIR /app

Install tools and dependencies

安装工具和依赖

RUN mise install
RUN mise install

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 shim mise reshim # 如有需要,重建 shims

**任务未找到**
```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> # 通过 verbose 输出查看环境加载情况 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>