Shren207 Nixos Config Managing Mise

mise 런타임 버전 관리

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

목적과 범위

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

빠른 참조

플랫폼별 설치 구조

mise 설정 위치

주요 명령어

# 현재 버전 확인
mise current

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

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

# 프로젝트 설정 신뢰
mise trust

관련 설정 파일

셸 활성화 구조

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

가드와 .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에 추가하여 회귀 조기 감지.

핵심 절차

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

자주 발생하는 문제

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

레퍼런스

• 트러블슈팅: references/troubleshooting.md

Source: shren207/nixos-config — distributed by TomeVault.