Development

mise로 개발 환경과 작업 명령 통일하기

프로젝트별 런타임 버전·환경 변수·반복 작업을 mise.toml에 묶고 로컬과 CI에서 같은 실행 환경을 재현하는 방법을 설명합니다.

mise는 프로젝트마다 Node.js·Python 같은 도구 버전, 환경 변수와 반복 작업을 mise.toml에 함께 선언하는 개발 환경 관리자입니다. 팀원이 서로 다른 전역 버전과 셸 설정 때문에 겪는 차이를 줄이고, 로컬·에디터·CI에서 같은 준비 과정을 재사용하고 싶을 때 유용합니다.

해결하는 문제

런타임 버전 관리, .env 로딩과 빌드 명령이 서로 다른 도구에 흩어지면 새 팀원이 프로젝트를 실행하기까지 여러 문서를 맞춰야 합니다. mise는 도구 선택과 작업 실행을 프로젝트 설정 가까이에 모읍니다. 모든 팀이 기존 버전 관리자를 즉시 바꿀 필요는 없지만, 새 저장소나 여러 언어가 섞인 프로젝트에서 작은 범위로 시험하기 좋습니다.

설치와 확인

공식 문서는 macOS와 Linux에서 단일 바이너리 설치 스크립트를 기본 경로로 안내합니다. 회사 장비에서는 원격 스크립트 정책을 먼저 확인하고 Homebrew, apt, winget 등 승인된 패키지 관리자를 선택할 수 있습니다.

curl https://mise.run | sh
~/.local/bin/mise --version

버전이 출력되면 설치가 끝났습니다. PATH를 바꾸지 않고도 ~/.local/bin/mise exec와 mise run을 쓸 수 있습니다. 대화형 셸에서 자동 전환을 원할 때만 zsh 설정에 활성화를 추가합니다.

echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc
exec zsh
mise doctor

mise doctor가 설치 위치와 셸 활성화를 정상으로 보고하면 다음 단계로 넘어갑니다. 셸 설정을 바꾸고 싶지 않다면 활성화 단계는 건너뛰고 모든 명령을 mise exec 또는 mise run으로 실행해도 됩니다.

일회성 버전 실행

프로젝트 설정을 만들기 전에 특정 버전을 한 번 시험할 수 있습니다.

mise exec node@24 -- node --version

필요한 Node.js가 없다면 mise가 설치한 뒤 실행합니다. 결과가 v24.로 시작하면 원하는 버전이 선택된 것입니다. 시스템 전역 Node.js를 바꾸지 않으므로 도입 전 검증에 적합합니다.

프로젝트 설정

빈 디렉터리에서 Node.js와 Python 버전, 환경 변수, 확인 작업을 함께 선언해봅니다.

mkdir mise-demo
cd mise-demo
mise use node@24
mise use python@3.13

명령이 만든 mise.toml을 열어 다음처럼 작업을 추가합니다.

[tools]
node = "24"
python = "3.13"

[env]
NODE_ENV = "development"

[tasks.check]
description = "선택된 런타임과 환경 확인"
run = '''
node --version
python --version
node -e "console.log(process.env.NODE_ENV)"
'''

설정 파일을 처음 받은 프로젝트라면 실행 전에 내용을 검토하세요. 일반 모드에서 mise install, mise exec, mise run은 활성 설정을 신뢰하고 프로젝트 동작을 실행할 수 있기 때문입니다.

mise install
mise tasks ls
mise run check

두 런타임 버전과 development가 출력되면 도구·환경·작업 연결이 정상입니다. mise tasks info check로 실제 실행 명령과 설명도 확인할 수 있습니다.

팀과 CI 적용

mise.toml을 버전 관리에 포함하면 팀원이 같은 버전 요청을 공유할 수 있습니다. 개인 토큰과 비밀값은 설정 파일에 직접 넣지 말고 조직의 비밀 저장소나 CI 환경 변수를 사용하세요. CI에서는 셸 프롬프트에 의존하는 활성화보다 mise install과 mise run check처럼 명시적인 명령이 이해하기 쉽습니다.

작업 의존성을 쓸 때는 의미를 확인해야 합니다. 공식 문서상 depends의 선행 작업은 병렬로 실행될 수 있으므로, 반드시 순서대로 끝나야 하는 명령은 하나의 run 배열이나 스크립트로 구성합니다.

설정 범위

mise use node@24: 현재 프로젝트 설정에 버전 요청을 기록합니다.
mise use --global node@24: 사용자 전역 설정에 기록하므로 프로젝트별 고정과 목적이 다릅니다.
mise exec -- <명령>: 현재 도구와 환경을 적용해 한 명령을 실행합니다.
mise run <작업>: mise.toml 또는 작업 파일에 선언된 반복 작업을 실행합니다.
mise tasks ls: 현재 발견된 작업 목록을 확인합니다.

설정 파일은 코드 실행과 환경 로딩에 영향을 줄 수 있습니다. 외부 저장소를 받은 직후에는 mise.toml, 작업 스크립트와 훅을 먼저 검토하고 무조건 신뢰하지 않는 것이 안전합니다.

문제 해결

mise 명령이 없으면 ~/.local/bin/mise --version과 command -v mise로 설치 위치를 확인합니다.
버전이 예상과 다르면 프로젝트 상위 디렉터리와 전역 설정에서 함께 로드된 설정을 점검합니다.
작업이 안 보이면 프로젝트 루트에서 mise tasks ls와 mise tasks info <이름>을 실행합니다.
설정 신뢰 경고가 나오면 파일과 작업 내용을 검토한 뒤에만 신뢰합니다.
GitHub 기반 도구 설치가 4xx로 실패하면 API 요청 제한 가능성을 확인하고 조직이 허용한 인증 경로를 사용합니다.
종합 진단은 mise doctor로 시작합니다.

제거와 복구

프로젝트에서 특정 버전 요청만 제거하려면 설정 범위를 확인한 뒤 mise unuse를 사용합니다. 설치 파일만 지우는 mise uninstall과 설정까지 수정하는 mise unuse는 역할이 다릅니다.

mise unuse node@24
mise uninstall --dry-run node@24

mise 자체를 제거할 때는 설치에 사용한 패키지 관리자를 우선 사용합니다. 단일 바이너리 설치였다면 먼저 mise implode --dry-run으로 삭제 범위를 확인하세요. 실제 mise implode는 CLI, 설치 도구, 캐시와 상태를 지울 수 있으므로 프로젝트의 mise.toml과 셸 설정을 별도로 확인한 뒤 실행해야 합니다. 도입을 되돌리는 가장 안전한 방법은 먼저 CI와 셸에서 mise run 의존을 제거하고 기존 실행 명령이 작동하는지 확인하는 것입니다.