mise 런타임 버전 관리 Skill

mise 런타임 버전 관리

mise를 사용한 Node.js, pnpm 등 런타임 버전 관리 가이드.

목적과 범위

런타임 버전 선택, shims 경로, SSH 비대화형 셸 이슈를 안정적으로 운영하는 절차를 다룬다. macOS·NixOS 모두 pkgs.mise(nix, libraries/packages.nix의 shared)로 설치한다. 과거 macOS에서 Homebrew로 mise를 수동 설치했다면 PATH 경합을 피하기 위해 brew uninstall mise를 권장한다.

빠른 참조

플랫폼별 설치 구조

| 항목 | macOS | NixOS | |------|-------|-------| | mise 설치 | libraries/packages.nix (shared, nix) | libraries/packages.nix (shared, nix) | | 소스 빌드 | 기본값 사용 | MISE_ALL_COMPILE=0 환경변수로 비활성화 | | Node 빌드 | 기본값 사용 | MISE_NODE_COMPILE=0 환경변수로 비활성화 | | 환경변수 위치 | - | modules/shared/programs/shell/nixos.nix |

mise 설정 위치

| 파일 | 용도 | |------|------| | ~/.config/mise/config.toml | 전역 설정 | | mise.toml / .mise.toml | 프로젝트별 설정 | | mise.local.toml | 프로젝트 로컬 (gitignore됨) | | .nvmrc, .node-version | Node.js 버전 (idiomatic files) |

주요 명령어

# 현재 버전 확인
mise current

# 전역 버전 설정
mise use -g node@lts

# 프로젝트 버전 설치
mise install node@20.18

# 프로젝트 설정 신뢰
mise trust

셸 활성화 구조

mise는 두 계층으로 활성화된다:

| 계층 | 파일 | 명령어 | 용도 | |------|------|--------|------| | .zshenv | shell/default.nix envExtra | mise activate zsh --shims | snapshot 미경유 비대화형(SSH zsh -c 등)에서 PATH에 shim 추가 | | .zshrc | shell/default.nix initContent | mise activate zsh + shims prepend | 대화형 훅(cd-time 버전 전환) + Claude Code snapshot 경유 비대화형 보강 |

가드와 .zshrc 추가 prepend의 배경:

가드 기반: shims 경로의 PATH 실재 여부로 중복 활성화를 판단한다 ([[ ":$PATH:" != *":$shims:"* ]]). shims 경로 fallback은 mise 공식 우선순위 MISE_DATA_DIR → $XDG_DATA_HOME/mise → $HOME/.local/share/mise를 따른다 (libraries/constants.nix의 mise.shimsDirExpr이 SoT).
옛 MISE_SHELL 가드 폐기 (#845): 부모 대화형 셸의 MISE_SHELL이 자식 비대화형 셸로 상속되어 shims 활성화를 조기 스킵하는 회귀를 만들어 폐기됐다.
.zshrc에서 shims prepend가 추가로 필요한 이유 (#857): Claude Code 같은 도구가 세션 시작 시 interactive 셸 PATH를 snapshot으로 박제하고 비대화형 호출마다 그 PATH를 복원한다. mise activate zsh(hook 모드)는 호출 끝에 _mise_hook을 즉시 발동시켜 install-bins를 PATH에 prepend하지만, hook 모드 정책상 shims는 PATH에 prepend하지 않는다 (shims는 --shims 플래그 경유에서만 PATH에 들어간다). 결과적으로 snapshot에는 install-bins는 들어가도 shims가 빠진 baseline이 박제되어, shim으로만 노출되는 도구(mise npm backend의 codex 등)는 비대화형에 미노출된다. .zshrc에서 shims를 명시적으로 prepend하면 snapshot에 shims도 포함되어 비대화형 호출이 동작한다.
위험·우려와 fallback 후보: 이 fix는 Claude Code snapshot 캡처 메커니즘에 간접 의존한다. 향후 캡처 방식 변경(예: sanitized PATH 기록) 시 회귀 재발 가능. fallback 후보는 (a) ~/.claude/settings.json의 env.PATH에 shims를 직접 prepend, (b) login shell init(.zprofile/.zlogin)에 shims 보강, (c) command -v codex 자가 검사를 verify-ai-compat에 추가하여 회귀 조기 감지.

핵심 절차

mise current로 현재 선택된 런타임을 확인한다.
전역 버전이 필요하면 mise use -g node@lts로 고정한다.
프로젝트별 버전은 mise.toml 또는 .nvmrc 기준으로 mise install을 실행한다.
.nvmrc 인식이 필요하면 mise settings add idiomatic_version_file_enable_tools node를 실행한다.
비대화형 셸 문제는 ~/.zshenv의 shims 경로와 mise activate 적용 여부를 점검한다.

자주 발생하는 문제

SSH 비대화형 세션에서 pnpm not found: .zshenv에 mise shims 누락 → 셸 활성화 구조 참조
.nvmrc 인식 안 됨: mise 2025.10.0부터 기본 비활성화 → idiomatic_version_file_enable_tools 설정 필요
NixOS에서 node 빌드 실패: MISE_NODE_COMPILE=0 필요 (현재 nixos.nix에서 영구 설정됨)
mise.local.toml 미신뢰: mise trust 실행 필요 (최초 1회)

레퍼런스

트러블슈팅: references/troubleshooting.md

Agent Skills: mise 런타임 버전 관리

Install this agent skill to your local

Skill Files