Back to Details

mise-configuration

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

mise Configuration as Single Source of Truth

以mise配置作为单一可信源（SSoT）

Use mise 
[env]
as centralized configuration with backward-compatible defaults.
将mise的
[env]
模块用作具备向后兼容默认值的集中化配置工具。

When to Use This Skill

何时使用该技能

Use this skill when:
  • Centralizing environment variables in mise.toml
  • Setting up Python venv auto-creation with mise
  • Implementing hub-spoke configuration for monorepos
  • Creating backward-compatible environment patterns
在以下场景中使用本技能：
  • 在mise.toml中集中管理环境变量
  • 通过mise自动创建Python虚拟环境（venv）
  • 为单体仓库实现中心辐射式配置
  • 创建向后兼容的环境配置模式

Core Principle

核心原则

Define all configurable values in 
.mise.toml
[env]
section. Scripts read via environment variables with fallback defaults. Same code path works WITH or WITHOUT mise installed.
Key insight: mise auto-loads 
[env]
values when shell has 
mise activate
configured. Scripts using 
os.environ.get("VAR", "default")
pattern work identically whether mise is present or not.
在
.mise.toml
的
[env]
部分定义所有可配置值。脚本通过环境变量读取配置，并附带回退默认值。无论是否安装mise，代码执行路径保持一致。
关键要点：当Shell配置了
mise activate
时，mise会自动加载
[env]
中的值。使用
os.environ.get("VAR", "default")
模式的脚本，无论mise是否存在，执行效果完全相同。

Quick Reference

快速参考

Language Patterns

语言适配模式

LanguagePatternNotes
Python
os.environ.get("VAR", "default")
Returns string, cast if int
Bash
${VAR:-default}
Standard POSIX expansion
JavaScript
process.env.VAR || "default"
Falsy check, watch for "0"
Go
os.Getenv("VAR")
with default		Empty string if unset
Rust
std::env::var("VAR").unwrap_or()
Returns Result<String>
语言适配模式说明
Python
os.environ.get("VAR", "default")
返回字符串，整数需自行转换
Bash
${VAR:-default}
标准POSIX扩展语法
JavaScript`process.env.VAR
Go
os.Getenv("VAR")
搭配默认值		未设置时返回空字符串
Rust
std::env::var("VAR").unwrap_or()
返回Result<String>类型

Special Directives

特殊指令

DirectivePurposeExample
_.file
Load from .env files
_.file = ".env"
_.path
Extend PATH
_.path = ["bin", "node_modules/.bin"]
_.source
Execute bash scripts
_.source = "./scripts/env.sh"
_.python.venv
Auto-create Python venv
_.python.venv = { path = ".venv", create = true }
指令用途示例
_.file
从.env文件加载配置
_.file = ".env"
_.path
扩展PATH环境变量
_.path = ["bin", "node_modules/.bin"]
_.source
执行Bash脚本
_.source = "./scripts/env.sh"
_.python.venv
自动创建Python虚拟环境
_.python.venv = { path = ".venv", create = true }

Python Venv Auto-Creation (Critical)

Python虚拟环境自动创建（核心功能）

Auto-create and activate Python virtual environments:
toml
[env]
_.python.venv = { path = ".venv", create = true }
This pattern is used in ALL projects. When entering the directory with mise activated:
  1. Creates 
    .venv
    if it doesn't exist
  2. Activates the venv automatically
  3. Works with 
    uv
    for fast venv creation
Alternative via [settings]:
toml
[settings]
python.uv_venv_auto = true
自动创建并激活Python虚拟环境：
toml
[env]
_.python.venv = { path = ".venv", create = true }
该模式适用于所有项目。当进入已配置mise activate的目录时：
  1. 若
    .venv
    不存在则自动创建
  2. 自动激活虚拟环境
  3. 可配合
    uv
    工具快速创建虚拟环境
通过[settings]配置的替代方案：
toml
[settings]
python.uv_venv_auto = true

Hub-Spoke Architecture (CRITICAL)

中心辐射式架构（核心功能）

Keep root 
mise.toml
lean by delegating domain-specific tasks to subfolder 
mise.toml
files.
Wiki Reference: Pattern-mise-Configuration - Complete documentation with CLAUDE.md footer prompt
通过将领域特定任务委托给子文件夹的mise.toml文件，保持根目录mise.toml的简洁性。
Wiki参考：Pattern-mise-Configuration - 完整文档，包含CLAUDE.md页脚提示

When to Use

适用场景

  • Root 
    mise.toml
    exceeds ~50 lines
  • Project has multiple domains (packages, experiments, infrastructure)
  • Different subfolders need different task sets
  • 根目录mise.toml超过约50行
  • 项目包含多个领域（包、实验、基础设施）
  • 不同子文件夹需要不同的任务集

Spoke Scenarios

辐射节点场景

Hub-spoke applies to any multi-domain project, not just packages:
ScenarioSpoke FoldersSpoke Tasks
Monorepo
packages/api/
, 
packages/web/
build, test, lint, deploy
ML/Research
experiments/exp-001/
, 
training/
, 
evaluation/
train, evaluate, notebook, sweep
Infrastructure
terraform/
, 
kubernetes/
, 
ansible/
plan, apply, deploy, validate
Data Pipeline
ingestion/
, 
transform/
, 
export/
extract, load, validate, export
中心辐射式架构适用于任何多领域项目，不仅限于软件包：
场景辐射节点文件夹辐射节点任务
单体仓库
packages/api/
, 
packages/web/
构建、测试、代码检查、部署
机器学习/研究
experiments/exp-001/
, 
training/
, 
evaluation/
训练、评估、笔记本运行、参数调优
基础设施
terraform/
, 
kubernetes/
, 
ansible/
规划、应用、部署、验证
数据流水线
ingestion/
, 
transform/
, 
export/
提取、加载、验证、导出

Directory Structure Examples

目录结构示例

Monorepo:
project/
├── mise.toml              # Hub: [tools] + [env] + orchestration
├── packages/
│   ├── api/mise.toml      # Spoke: API tasks
│   └── web/mise.toml      # Spoke: Web tasks
└── scripts/mise.toml      # Spoke: Utility scripts
ML/Research Project:
ml-project/
├── mise.toml              # Hub: python, cuda, orchestration
├── experiments/
│   ├── baseline/mise.toml # Spoke: baseline experiment
│   └── ablation/mise.toml # Spoke: ablation study
├── training/mise.toml     # Spoke: training pipelines
└── evaluation/mise.toml   # Spoke: metrics, benchmarks
Infrastructure:
infra/
├── mise.toml              # Hub: terraform, kubectl, helm
├── terraform/
│   ├── prod/mise.toml     # Spoke: production infra
│   └── staging/mise.toml  # Spoke: staging infra
└── kubernetes/mise.toml   # Spoke: k8s manifests
单体仓库：
project/
├── mise.toml              | 中心节点：[工具] + [环境] + 编排
├── packages/
│   ├── api/mise.toml      | 辐射节点：API任务
│   └── web/mise.toml      | 辐射节点：Web任务
└── scripts/mise.toml      | 辐射节点：实用脚本
机器学习/研究项目：
ml-project/
├── mise.toml              | 中心节点：Python、CUDA、编排
├── experiments/
│   ├── baseline/mise.toml | 辐射节点：基准实验
│   └── ablation/mise.toml | 辐射节点：消融实验
├── training/mise.toml     | 辐射节点：训练流水线
└── evaluation/mise.toml   | 辐射节点：指标、基准测试
基础设施：
infra/
├── mise.toml              | 中心节点：Terraform、Kubectl、Helm
├── terraform/
│   ├── prod/mise.toml     | 辐射节点：生产环境基础设施
│   └── staging/mise.toml  | 辐射节点：预发布环境基础设施
└── kubernetes/mise.toml   | 辐射节点：K8s清单

Hub Responsibilities (Root 
mise.toml
)

中心节点职责（根目录mise.toml）

toml
undefined
toml
undefined

mise.toml - Hub: Keep this LEAN

mise.toml - 中心节点：保持简洁

[tools] python = "<version>" uv = "latest"
[env] PROJECT_NAME = "my-project" _.python.venv = { path = ".venv", create = true }
[tools] python = "<版本号>" uv = "latest"
[env] PROJECT_NAME = "my-project" _.python.venv = { path = ".venv", create = true }

Orchestration: delegate to spokes

编排：委托给辐射节点

[tasks.train-all] run = """ cd experiments/baseline && mise run train cd experiments/ablation && mise run train """
[tasks."build:api"] run = "cd packages/api && mise run build"
undefined
[tasks.train-all] run = """ cd experiments/baseline && mise run train cd experiments/ablation && mise run train """
[tasks."build:api"] run = "cd packages/api && mise run build"
undefined

Spoke Responsibilities (Subfolder 
mise.toml
)

辐射节点职责（子文件夹mise.toml）

toml
undefined
toml
undefined

experiments/baseline/mise.toml - Spoke

experiments/baseline/mise.toml - 辐射节点

[env] EXPERIMENT_NAME = "baseline" EPOCHS = "<num>" # e.g., 100 LEARNING_RATE = "<float>" # e.g., 0.001
[tasks.train] run = "uv run python train.py" sources = [".py", "config.yaml"] outputs = ["checkpoints/.pt"]
[tasks.evaluate] depends = ["train"] run = "uv run python evaluate.py"
undefined
[env] EXPERIMENT_NAME = "baseline" EPOCHS = "<数值>" # 例如：100 LEARNING_RATE = "<浮点数>" # 例如：0.001
[tasks.train] run = "uv run python train.py" sources = [".py", "config.yaml"] outputs = ["checkpoints/.pt"]
[tasks.evaluate] depends = ["train"] run = "uv run python evaluate.py"
undefined

Inheritance Rules

继承规则

  • Spoke 
    mise.toml
    inherits hub's 
    [tools]
    automatically
  • Spoke 
    [env]
    extends hub's 
    [env]
    (can override per domain)
  • .mise.local.toml
    applies at directory level (secrets stay local)
  • 辐射节点的mise.toml会自动继承中心节点的
    [tools]
    配置
  • 辐射节点的
    [env]
    会扩展中心节点的
    [env]
    （可按领域覆盖）
  • .mise.local.toml
    在目录级别生效（敏感信息保存在本地）

Anti-Patterns

反模式

Anti-PatternProblemFix
All tasks in rootRoot grows to 200+ linesDelegate to spoke files
Duplicated [tools]Version drift between spokesDefine [tools] only in hub
Spoke defines runtimesConflicts with hubSpokes inherit hub's [tools]
No orchestrationMust cd manuallyHub orchestrates spoke tasks
反模式问题解决方案
所有任务都放在根目录根目录文件膨胀至200+行将任务委托给辐射节点文件
重复定义[tools]配置辐射节点间版本不一致仅在中心节点定义[tools]
辐射节点定义运行时环境与中心节点冲突辐射节点继承中心节点的[tools]
无编排逻辑需手动切换目录执行命令中心节点编排辐射节点任务

Monorepo Workspace Pattern

单体仓库工作区模式

For Python monorepos using 
uv
workspaces, the venv is created at the workspace root. Sub-packages share the root venv.
toml
undefined
对于使用
uv
工作区的Python单体仓库，虚拟环境需在工作区根目录创建。子包共享根目录的虚拟环境。
toml
undefined

Root mise.toml

根目录mise.toml

[env] _.python.venv = { path = ".venv", create = true }
undefined
[env] _.python.venv = { path = ".venv", create = true }
undefined

Hoisted Dev Dependencies (PEP 735)

提升开发依赖至根目录（PEP 735）

Dev dependencies (
pytest
, 
ruff
, 
jupyterlab
, etc.) should be hoisted to workspace root 
pyproject.toml
using 
[dependency-groups]
:
toml
undefined
开发依赖（如
pytest
、
ruff
、
jupyterlab
等）应通过
[dependency-groups]
提升至工作区根目录的
pyproject.toml
中：
toml
undefined

SSoT-OK: example workspace configuration

符合SSoT的示例工作区配置

Root pyproject.toml

根目录pyproject.toml

[tool.uv.workspace] members = ["packages/*"]
[dependency-groups] dev = [ "pytest>=<version>", "ruff>=<version>", "jupyterlab>=<version>", ]

**Why hoist?** Sub-package `[dependency-groups]` are NOT automatically installed by `uv sync` from root. Hoisting ensures:

- Single command: `uv sync --group dev`
- No "unnecessary package" warnings
- Unified dev environment across all packages

> **Reference**: [bootstrap-monorepo.md](../mise-tasks/references/bootstrap-monorepo.md#root-pyprojecttoml-workspace) for complete workspace setup
[tool.uv.workspace] members = ["packages/*"]
[dependency-groups] dev = [ "pytest>=<版本号>", "ruff>=<版本号>", "jupyterlab>=<版本号>", ]

**为什么要提升？** 子包的`[dependency-groups]`不会被`uv sync`从根目录自动安装。提升依赖可确保：

- 单命令完成安装：`uv sync --group dev`
- 无"不必要包"警告
- 所有子包使用统一的开发环境

> **参考**：[bootstrap-monorepo.md](../mise-tasks/references/bootstrap-monorepo.md#root-pyprojecttoml-workspace) 完整工作区设置指南

Special Directives

特殊指令详解

Load from .env Files (
_.file
)

从.env文件加载配置（
_.file
）

toml
[env]
toml
[env]

Single file

加载单个文件

_.file = ".env"
_.file = ".env"

Multiple files with options

加载多个文件并配置选项

_.file = [ ".env", { path = ".env.secrets", redact = true } ]
undefined
_.file = [ ".env", { path = ".env.secrets", redact = true } ]
undefined

Extend PATH (
_.path
)

扩展PATH环境变量（
_.path
）

toml
[env]
_.path = [
    "{{config_root}}/bin",
    "{{config_root}}/node_modules/.bin",
    "scripts"
]
toml
[env]
_.path = [
    "{{config_root}}/bin",
    "{{config_root}}/node_modules/.bin",
    "scripts"
]

Source Bash Scripts (
_.source
)

执行Bash脚本（
_.source
）

toml
[env]
_.source = "./scripts/env.sh"
_.source = { path = ".secrets.sh", redact = true }
toml
[env]
_.source = "./scripts/env.sh"
_.source = { path = ".secrets.sh", redact = true }

Lazy Evaluation (
tools = true
)

延迟求值（
tools = true
）

By default, env vars resolve BEFORE tools install. Use 
tools = true
to access tool-generated paths:
toml
[env]
默认情况下，环境变量在工具安装前解析。使用
tools = true
可访问工具生成的路径：
toml
[env]

Access PATH after tools are set up

在工具设置完成后访问PATH

GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }
GEM_BIN = { value = "{{env.GEM_HOME}}/bin", tools = true }

Load .env files after tool setup

在工具设置完成后加载.env文件

_.file = { path = ".env", tools = true }
undefined
_.file = { path = ".env", tools = true }
undefined

Template Syntax (Tera)

模板语法（Tera）

mise uses Tera templating. Delimiters: 
{{ }}
expressions, 
{% %}
statements, 
{# #}
comments.
mise使用Tera模板引擎。分隔符：
{{ }}
表达式、
{% %}
语句、
{# #}
注释。

Built-in Variables

内置变量

VariableDescription
{{config_root}}
Directory containing .mise.toml
{{cwd}}
Current working directory
{{env.VAR}}
Environment variable
{{mise_bin}}
Path to mise binary
{{mise_pid}}
mise process ID
{{xdg_cache_home}}
XDG cache directory
{{xdg_config_home}}
XDG config directory
{{xdg_data_home}}
XDG data directory
变量描述
{{config_root}}
包含.mise.toml的目录
{{cwd}}
当前工作目录
{{env.VAR}}
环境变量
{{mise_bin}}
mise二进制文件路径
{{mise_pid}}
mise进程ID
{{xdg_cache_home}}
XDG缓存目录
{{xdg_config_home}}
XDG配置目录
{{xdg_data_home}}
XDG数据目录

Functions

内置函数

toml
[env]
toml
[env]

Get env var with fallback

获取环境变量，带默认值

NODE_VER = "{{ get_env(name='NODE_VERSION', default='20') }}"
NODE_VER = "{{ get_env(name='NODE_VERSION', default='20') }}"

Execute shell command

执行Shell命令

TIMESTAMP = "{{ exec(command='date +%Y-%m-%d') }}"
TIMESTAMP = "{{ exec(command='date +%Y-%m-%d') }}"

System info

系统信息

ARCH = "{{ arch() }}" # x64, arm64 OS = "{{ os() }}" # linux, macos, windows CPUS = "{{ num_cpus() }}"
ARCH = "{{ arch() }}" # x64, arm64 OS = "{{ os() }}" # linux, macos, windows CPUS = "{{ num_cpus() }}"

File operations

文件操作

VERSION = "{{ read_file(path='VERSION') | trim }}" HASH = "{{ hash_file(path='config.json', len=8) }}"
undefined
VERSION = "{{ read_file(path='VERSION') | trim }}" HASH = "{{ hash_file(path='config.json', len=8) }}"
undefined

Filters

过滤器

toml
[env]
toml
[env]

Case conversion

大小写转换

SNAKE = "{{ name | snakecase }}" KEBAB = "{{ name | kebabcase }}" CAMEL = "{{ name | lowercamelcase }}"
SNAKE = "{{ name | snakecase }}" KEBAB = "{{ name | kebabcase }}" CAMEL = "{{ name | lowercamelcase }}"

String manipulation

字符串操作

TRIMMED = "{{ text | trim }}" UPPER = "{{ text | upper }}" REPLACED = "{{ text | replace(from='old', to='new') }}"
TRIMMED = "{{ text | trim }}" UPPER = "{{ text | upper }}" REPLACED = "{{ text | replace(from='old', to='new') }}"

Path operations

路径操作

ABSOLUTE = "{{ path | absolute }}" BASENAME = "{{ path | basename }}" DIRNAME = "{{ path | dirname }}"
undefined
ABSOLUTE = "{{ path | absolute }}" BASENAME = "{{ path | basename }}" DIRNAME = "{{ path | dirname }}"
undefined

Conditionals

条件语句

toml
[env]
{% if env.DEBUG %}
LOG_LEVEL = "debug"
{% else %}
LOG_LEVEL = "info"
{% endif %}
toml
[env]
{% if env.DEBUG %}
LOG_LEVEL = "debug"
{% else %}
LOG_LEVEL = "info"
{% endif %}

Required & Redacted Variables

必填与脱敏变量

Required Variables

必填变量

Enforce variable definition with helpful messages:
toml
[env]
DATABASE_URL = { required = true }
API_KEY = { required = "Get from https://example.com/api-keys" }
强制要求定义变量并提供友好提示：
toml
[env]
DATABASE_URL = { required = true }
API_KEY = { required = "从https://example.com/api-keys获取" }

Redacted Variables

脱敏变量

Hide sensitive values from output:
toml
[env]
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }
在输出中隐藏敏感值：
toml
[env]
SECRET = { value = "my_secret", redact = true }
_.file = { path = ".env.secrets", redact = true }

Pattern-based redactions

基于模式的脱敏

redactions = ["_TOKEN", "_KEY", "PASSWORD"]
undefined
redactions = ["_TOKEN", "_KEY", "PASSWORD"]
undefined

[settings] Section

[settings]配置段

toml
[settings]
experimental = true              # Enable experimental features
python.uv_venv_auto = true       # Auto-create venv with uv
toml
[settings]
experimental = true              # 启用实验性功能
python.uv_venv_auto = true       # 配合uv自动创建虚拟环境

[tools] Version Pinning

[tools]版本固定

Pin tool versions for reproducibility:
toml
[tools]
python = "3.11"  # minimum baseline; use 3.12, 3.13 as needed
node = "latest"
uv = "latest"
固定工具版本以保证可复现性：
toml
[tools]
python = "3.11"  # 最低基线版本；可根据需要使用3.12、3.13
node = "latest"
uv = "latest"

With options

带选项的配置

rust = { version = "1.75", profile = "minimal" }

**min_version**: Enforce mise version compatibility:

```toml
min_version = "2024.9.5"
rust = { version = "1.75", profile = "minimal" }

**min_version**：强制mise版本兼容性：

```toml
min_version = "2024.9.5"

Implementation Steps

实施步骤

  1. Identify hardcoded values - timeouts, paths, thresholds, feature flags
  2. Create 
    .mise.toml
     - add 
    [env]
    section with documented variables
  3. Add venv auto-creation - 
    _.python.venv = { path = ".venv", create = true }
  4. Update scripts - use env vars with original values as defaults
  5. Add ADR reference - comment: 
    # ADR: 2025-12-08-mise-env-centralized-config
  6. Test without mise - verify script works using defaults
  7. Test with mise - verify activated shell uses 
    .mise.toml
    values
  1. 识别硬编码值 - 超时时间、路径、阈值、功能开关
  2. 创建.mise.toml - 添加
    [env]
    段并记录变量说明
  3. 添加虚拟环境自动创建 - 配置
    _.python.venv = { path = ".venv", create = true }
  4. 更新脚本 - 使用环境变量并保留原始值作为默认值
  5. 添加ADR参考 - 注释：
    # ADR: 2025-12-08-mise-env-centralized-config
  6. 无mise环境测试 - 验证脚本使用默认值可正常运行
  7. 有mise环境测试 - 验证激活Shell后使用.mise.toml中的值

GitHub Token Multi-Account Patterns (MANDATORY for Multi-Account Setups) {#github-token-multi-account-patterns}

GitHub多账号令牌模式（多账号设置必备） {#github-token-multi-account-patterns}

For multi-account GitHub setups, mise 
[env]
provides per-directory token configuration that overrides gh CLI's global authentication.
对于GitHub多账号设置，mise 
[env]
提供按目录配置令牌的功能，可覆盖gh CLI的全局认证。

Token Storage

令牌存储

Store tokens in a centralized, secure location:
bash
mkdir -p ~/.claude/.secrets
chmod 700 ~/.claude/.secrets
将令牌存储在集中的安全位置：
bash
mkdir -p ~/.claude/.secrets
chmod 700 ~/.claude/.secrets

Create token files (one per account)

创建令牌文件（每个账号一个）

gh auth login # authenticate as account gh auth token > ~/.claude/.secrets/gh-token-accountname chmod 600 ~/.claude/.secrets/gh-token-*
undefined
gh auth login # 以目标账号认证 gh auth token > ~/.claude/.secrets/gh-token-accountname chmod 600 ~/.claude/.secrets/gh-token-*
undefined

Per-Directory Configuration

按目录配置

toml
undefined
toml
undefined

~/.claude/.mise.toml (terrylica account)

~/.claude/.mise.toml（terrylica账号）

[env] GH_TOKEN = "{{ read_file(path=config_root ~ '/.secrets/gh-token-terrylica') | trim }}" GITHUB_TOKEN = "{{ read_file(path=config_root ~ '/.secrets/gh-token-terrylica') | trim }}" GH_ACCOUNT = "terrylica" # For human reference only

```toml
[env] GH_TOKEN = "{{ read_file(path=config_root ~ '/.secrets/gh-token-terrylica') | trim }}" GITHUB_TOKEN = "{{ read_file(path=config_root ~ '/.secrets/gh-token-terrylica') | trim }}" GH_ACCOUNT = "terrylica" # 仅用于人工参考

```toml

~/eon/.mise.toml (terrylica account - different directory)

~/eon/.mise.toml（terrylica账号 - 不同目录）

[env] GH_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-terrylica') | trim }}" GITHUB_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-terrylica') | trim }}" GH_ACCOUNT = "terrylica"
undefined
[env] GH_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-terrylica') | trim }}" GITHUB_TOKEN = "{{ read_file(path=env.HOME ~ '/.claude/.secrets/gh-token-terrylica') | trim }}" GH_ACCOUNT = "terrylica"
undefined

Variable Naming Convention

变量命名规范

VariableUsage ContextExample
GH_TOKEN
mise [env], Doppler, verification tasks
.mise.toml
, shell scripts
GITHUB_TOKEN
npm scripts, GitHub Actions, semantic-release
package.json
, workflows
Rule: Always set BOTH variables in mise [env] pointing to the same token file. Different tools check different variable names.
变量名使用场景示例
GH_TOKEN
mise [env]、Doppler、验证任务
.mise.toml
、Shell脚本
GITHUB_TOKEN
npm脚本、GitHub Actions、语义化版本发布
package.json
、工作流
规则：在mise [env]中始终同时设置两个变量，指向同一个令牌文件。不同工具会检查不同的变量名。

Alternative: 1Password Integration

替代方案：1Password集成

For enhanced security with automatic token rotation:
toml
[env]
GH_TOKEN = "{{ op_read('op://Engineering/GitHub Token/credential') }}"
With caching for performance:
toml
[env]
GH_TOKEN = "{{ cache(key='gh_token', duration='1h', run='op read op://Engineering/GitHub Token/credential') }}"
通过自动令牌轮换增强安全性：
toml
[env]
GH_TOKEN = "{{ op_read('op://Engineering/GitHub Token/credential') }}"
搭配缓存提升性能：
toml
[env]
GH_TOKEN = "{{ cache(key='gh_token', duration='1h', run='op read op://Engineering/GitHub Token/credential') }}"

Verification

验证

bash
/usr/bin/env bash << 'MISE_EOF'
for dir in ~/.claude ~/eon ~/own ~/scripts ~/459ecs; do
  cd "$dir" && eval "$(mise hook-env -s bash)" && echo "$dir → $GH_ACCOUNT"
done
MISE_EOF
Pattern: Based on GitHub Multi-Account Authentication ADR (mise 
[env]
per-directory token loading).
SSH ControlMaster Warning: If using multi-account SSH, ensure 
ControlMaster no
is set for GitHub hosts in 
~/.ssh/config
. Cached connections can authenticate with the wrong account. See SSH ControlMaster Cache for troubleshooting.
bash
/usr/bin/env bash << 'MISE_EOF'
for dir in ~/.claude ~/eon ~/own ~/scripts ~/459ecs; do
  cd "$dir" && eval "$(mise hook-env -s bash)" && echo "$dir → $GH_ACCOUNT"
done
MISE_EOF
模式依据：基于GitHub多账号认证ADR（mise 
[env]
按目录加载令牌）。
SSH ControlMaster警告：如果使用多账号SSH，请确保在
~/.ssh/config
中为GitHub主机设置
ControlMaster no
。缓存的连接可能导致使用错误账号认证。故障排除请参考SSH ControlMaster缓存。

Anti-Patterns

反模式汇总

Anti-PatternWhyInstead
mise exec -- script.py
Forces mise dependencyUse env vars with defaults
Secrets in 
.mise.toml
Visible in repoUse Doppler or 
redact = true
No defaults in scriptsBreaks without miseAlways provide fallback
Mixing env/tools resolutionOrder mattersUse 
tools = true
for tool-dependent vars
反模式问题原因正确做法
mise exec -- script.py
强制依赖mise环境使用带默认值的环境变量
在.mise.toml中存储敏感信息敏感信息会被提交到仓库使用Doppler或
redact = true
配置
脚本中未设置默认值无mise环境时脚本失效始终提供回退默认值
混合环境/工具解析时机解析顺序会影响结果对依赖工具的变量使用
tools = true
选项

Task Orchestration Integration

任务编排集成

When you detect workflow opportunities during mise configuration, prescriptively invoke the 
mise-tasks
skill.
在配置mise时若发现工作流优化机会，请主动调用
mise-tasks
技能。

Detection Triggers

检测触发条件

  • Multi-step workflows (test + build + deploy)
  • Repeatable project commands (lint, format, release)
  • Dependency chains (db-migrate depends on db-init)
  • File-tracked builds (sources/outputs caching)
  • 多步骤工作流（测试+构建+部署）
  • 可重复的项目命令（代码检查、格式化、发布）
  • 依赖链（数据库迁移依赖数据库初始化）
  • 文件追踪构建（源文件/输出文件缓存）

Prescriptive AI Reminder

规范性AI提示

PRESCRIPTIVE: When detecting multi-step project workflows, invoke 
mise-tasks
skill to generate appropriate 
[tasks]
definitions with dependency management.
规范性要求：当检测到多步骤项目工作流时，**调用
mise-tasks
技能**生成带依赖管理的
[tasks]
定义。

Example: From Environment to Tasks

示例：从环境配置到任务编排

Step 1: Configure environment (this skill):
toml
[env]
DATABASE_URL = "postgresql://localhost/mydb"
_.python.venv = { path = ".venv", create = true }
Step 2: Define tasks (
mise-tasks
skill):
toml
[tasks.test]
depends = ["lint"]
run = "pytest tests/"

[tasks.deploy]
depends = ["test", "build"]
run = "deploy.sh"
Tasks automatically inherit 
[env]
values.
步骤1：配置环境（本技能）：
toml
[env]
DATABASE_URL = "postgresql://localhost/mydb"
_.python.venv = { path = ".venv", create = true }
步骤2：定义任务（
mise-tasks
技能）：
toml
[tasks.test]
depends = ["lint"]
run = "pytest tests/"

[tasks.deploy]
depends = ["test", "build"]
run = "deploy.sh"
任务会自动继承
[env]
中的值。

Additional Resources

额外资源

For complete code patterns and examples, see: 
references/patterns.md
For task orchestration, see: 
mise-tasks
skill - Dependencies, arguments, file tracking, watch mode
Wiki Documentation: Pattern-mise-Configuration - Copyable CLAUDE.md footer prompt, hub-spoke architecture, quick reference
ADR Reference: When implementing mise configuration, create an ADR at 
docs/adr/YYYY-MM-DD-mise-env-centralized-config.md
in your project.
完整代码模式与示例请参考：
references/patterns.md
任务编排相关：请参考**
mise-tasks
技能** - 依赖管理、参数传递、文件追踪、监听模式
Wiki文档：Pattern-mise-Configuration - 可复制的CLAUDE.md页脚提示、中心辐射式架构、快速参考
ADR参考：实施mise配置时，请在项目中创建ADR文档：
docs/adr/YYYY-MM-DD-mise-env-centralized-config.md

Troubleshooting

故障排除

IssueCauseSolution
Env vars not loadingmise not activatedAdd mise activate to shell rc file
Venv not createdPython not installedRun 
mise install python
Tasks not foundWrong mise.toml locationEnsure mise.toml is in project root
PATH not updatedShims not in PATHAdd mise shims to ~/.zshenv
_.file not loading.env file missingCreate .env file or remove _.file directive
Subfolder config ignoredMissing min_versionAdd min_version to subfolder mise.toml
问题原因解决方案
环境变量未加载mise未激活将mise activate添加到Shell配置文件中
虚拟环境未创建Python未安装执行
mise install python
任务未找到mise.toml位置错误确保mise.toml在项目根目录中
PATH未更新Shims未加入PATH将mise shims添加到~/.zshenv
_.file
未加载		.env文件缺失创建.env文件或移除
_.file
指令
子文件夹配置被忽略缺少min_version配置在子文件夹mise.toml中添加min_version