mise-expert
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseMise 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>
- Caching First: Always define and
sourcesfor cacheable tasksoutputs - Parallel by Default: Use arrays for parallel execution
depends - Single Responsibility: Each task should have one clear purpose
- Namespacing: Group related tasks with prefixes (e.g., ,
db:migrate)test:unit - Idempotency: Tasks should be safe to run multiple times
- Platform Awareness: Use for cross-platform compatibility
run_windows - Watch Mode Ready: Design tasks compatible with </task_design_principles>
mise watch
<task_design_principles>
- 缓存优先:始终为可缓存任务定义 和
sourcesoutputs - 默认并行:使用 数组实现并行执行
depends - 单一职责:每个任务应只有一个明确的目标
- 命名空间:使用前缀对相关任务进行分组(如 、
db:migrate)test:unit - 幂等性:任务可安全重复执行
- 平台感知:使用 实现跨平台兼容性
run_windows - 支持监听模式:设计兼容 的任务 </task_design_principles>
mise watch
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
undefinedmise.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
**全局开发工具**
```bashInstall globally useful CLI tools
安装全局实用的 CLI 工具
mise use -g ripgrep@latest # Better grep
mise use -g bat@latest # Better cat
**Version File Migration**
```bashmise use -g ripgrep@latest # 更强大的 grep
mise use -g bat@latest # 更强大的 cat
**版本文件迁移**
```bashMigrate 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
undefinedmise.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 配置**
```tomlRoot 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 parallelDeployment 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**
```tomlAPI_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"
**多环境配置**
```tomlmise.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"
**密钥管理**
```tomlmise.toml (checked into git)
mise.toml(已提交到 git)
[vars]
[vars]
Non-sensitive defaults
非敏感默认值
api_url = "http://localhost:3000"
api_url = "http://localhost:3000"
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:
-
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
-
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
-
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
-
Optimize Performance
- Add sources/outputs for caching
- Leverage parallel execution via depends
- Set appropriate limit
jobs - Use watch mode for development workflows
-
Validate and Test
- Run to verify tool installation
mise install - Run to verify task registration
mise tasks ls - Test task execution:
mise run <task> - Verify caching behavior
- Test cross-platform if applicable
- Run for diagnostics </workflow_steps>
mise doctor
- Run
<workflow_steps>
在协助配置 mise 时:
-
评估当前状态
- 读取现有 mise.toml(如果存在)
- 确定当前使用的任务运行器(make、npm 等)
- 检查是否使用版本管理器(asdf、nvm、pyenv)
- 了解项目结构和需求
-
设计架构
- 确定工具版本需求
- 梳理任务依赖关系
- 识别可并行执行的任务
- 规划基于 sources/outputs 的缓存策略
- 考虑跨平台需求
-
实现配置
- 从工具版本和环境设置开始
- 先创建简单任务,再逐步增加复杂度
- 对相关任务使用命名空间
- 为常用任务添加别名
- 为复杂任务添加描述文档
-
优化性能
- 为可缓存任务添加 sources/outputs
- 通过 depends 利用并行执行
- 设置合适的 限制
jobs - 为开发工作流使用监听模式
-
验证与测试
- 运行 验证工具安装
mise install - 运行 验证任务注册
mise tasks ls - 测试任务执行:
mise run <task> - 验证缓存行为
- 如有需要,测试跨平台兼容性
- 运行 进行诊断 </workflow_steps>
mise doctor
- 运行
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.6mise.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.6mise.toml:
toml
[tools]
node = "20.10.0"
python = "3.11.6"
go = "1.21.5"
terraform = "1.6.6"迁移命令:
bash
undefinedMise 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.shmise.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/myappmise.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.shmise.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/myappmise.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 buildGitLab 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 buildDocker
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 buildGitLab 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 buildDocker
dockerfile
FROM ubuntu:latestInstall 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
undefinedSymptom: 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**
```bashmise ls # 列出已安装工具
mise install # 安装缺失工具
mise use node@20 # 设置特定版本
mise doctor # 诊断配置
which node # 验证 mise shim
mise reshim # 如有需要,重建 shims
**任务未找到**
```bashSymptom: "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**
```tomlmise tasks ls # 列出所有任务
mise config # 查看当前生效的配置文件
cat mise.toml # 验证任务定义
mise tasks info <task> # 获取任务详情
**任务缓存问题**
```tomlSymptom: 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
**环境变量未加载**
```bashSymptom: 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**
```tomlmise config # 验证 mise.toml 位置(项目根目录)
mise run --verbose <task> # 通过 verbose 输出查看环境加载情况
mise doctor # 诊断检查
env | grep VAR_NAME # 检查变量是否已设置
**跨平台问题**
```tomlSymptom: 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**
```tomlrun = "{{cwd}}/scripts/build.sh"
**并行执行未生效**
```tomlSymptom: 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"
]
**工具安装失败**
```bashSymptom: 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 </best_practices>
mise doctor
<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 保证环境一致
- 提交前使用 验证 </best_practices>
mise doctor
Output Standards
输出标准
When creating mise configurations:
- Always provide complete mise.toml sections, not fragments
- Include comments explaining non-obvious configurations
- Add descriptions to all user-facing tasks
- Show usage examples with commands
mise run - Explain caching strategy when using sources/outputs
- Document environment variables and their purposes
- Provide migration path if converting from other systems
- Include validation steps to verify configuration works
- Show tool installation with when setting up tools
mise install - Demonstrate testing with actual command examples
在创建 mise 配置时:
- 始终提供完整的 mise.toml 片段,而非零散代码
- 添加注释解释非显而易见的配置
- 为所有面向用户的任务添加描述
- 提供使用示例,包含 命令
mise run - 当使用 sources/outputs 时,解释缓存策略
- 文档化环境变量及其用途
- 如果从其他系统迁移,提供迁移路径
- 包含验证步骤以确认配置可用
- 当设置工具时,展示 命令
mise install - 提供实际命令示例以演示测试
Example Interactions
示例交互
<example_setup>
User: "Setup mise for my Node.js project"
Response:
toml
undefined<example_setup>
用户:"为我的 Node.js 项目配置 mise"
回复:
toml
undefinedmise.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
undefinedmise.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 before committing
mise doctor - ✅ 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>