Claude Code Windows 설치 오류: npm 글로벌 설치 문제 해결 완벽 가이드

문제 상황 개요

동일한 Windows 11 환경의 두 대의 PC에서 npm i -g @anthropic-ai/claude-code 명령어를 실행했을 때 전혀 다른 결과가 발생했습니다.

PC A (정상): D:\node\nodejs\node_global\node_modules\@anthropic-ai\claude-code\bin\claude.exe 파일 크기가 약 234MB였으며, claude 명령어가 정상적으로 동작했습니다.
PC B (비정상): 동일한 명령어 실행 후 claude.exe 파일 크기가 약 1KB에 불과했으며, 이는 npm 저장소에 등록된 소스 파일 크기와 동일합니다. claude 명령어 실행이 불가능했습니다.

핵심 의문점

npm 저장소에 표시된 claude.exe는 1KB인데, PC A에서는 왜 234MB로 나타나는가?
동일한 Windows 11 환경임에도 PC B에서 정상적인 234MB 바이너리를 받지 못한 이유는?
PC B에서 win32-x64 플랫폼용 네이티브 바이너리를 재설치하는 방법은?

환경 정보

항목	값
운영체제	Windows 11 Pro (두 PC 모두)
패키지 매니저	npm (글로벌 설치)
Node 글로벌 디렉토리	`D:\node\nodejs\node_global\`
대상 패키지	`@anthropic-ai/claude-code` (버전 `2.1.114`)
대상 CPU 아키텍처	`win32-x64`
Node 요구사항	`>=18.0.0`

빠른 결론

npm 저장소에 있는 bin/claude.exe는 1KB 크기의 스텁(stub) 파일입니다. 실제 바이너리는 플랫폼별 optionalDependencies 서브 패키지에 포함되어 있으며, postinstall 스크립트(install.cjs)가 설치 시점에 하드 링크하여 교체합니다.
PC B에서 실패한 이유는 플랫폼 서브 패키지 @anthropic-ai/claude-code-win32-x64가 제대로 설치되지 않았기 때문입니다. 주로 미러 저장소 미동기, optional 의존성 비활성화, postinstall 스크립트 생략 등이 원인입니다.
수정 명령어 (단일 명령어로 해결 가능):
npm i -g @anthropic-ai/claude-code --include=optional --foreground-scripts --registry=https://registry.npmjs.org/ --verbose

아래에서 전체적인 원리, 진단 방법, 수정 방안을 상세히 설명하겠습니다.

1. 패키지 아키텍처 이해

@anthropic-ai/claude-code는 배포용 셸 패키지입니다. 실제 네이티브 바이너리는 8개의 플랫폼별 optionalDependencies 서브 패키지에 포함되어 있습니다.

@anthropic-ai/claude-code              ← 메인 패키지 (~수 MB, install.cjs 포함)
├── @anthropic-ai/claude-code-win32-x64    ← Windows x64 네이티브 exe (~234MB)
├── @anthropic-ai/claude-code-win32-arm64
├── @anthropic-ai/claude-code-darwin-arm64
├── @anthropic-ai/claude-code-darwin-x64
├── @anthropic-ai/claude-code-linux-x64
├── @anthropic-ai/claude-code-linux-arm64
├── @anthropic-ai/claude-code-linux-x64-musl
└── @anthropic-ai/claude-code-linux-arm64-musl

설치 과정

npm이 메인 패키지를 다운로드하며, bin/claude.exe는 1KB 스텁 파일입니다.
npm은 현재 플랫폼에 맞는 하나의 서브 패키지만 optionalDependencies에서 선택하여 다운로드합니다 (Windows x64는 claude-code-win32-x64).
메인 패키지의 postinstall 스크립트 install.cjs가 실행되어 다음 작업을 수행합니다:
- require.resolve로 플랫폼 서브 패키지의 실제 바이너리 경로를 확인
- linkSync(하드 링크, 디스크 추가 사용 없음) 또는 copyFileSync(크로스 드라이브/권한 문제 시) 사용
- 메인 패키지의 bin/claude.exe 스텁 파일을 덮어쓰기

설치 성공 여부는 bin/claude.exe 파일 크기가 약 234MB인지 확인하면 됩니다 (nlink=2는 하드 링크임을 의미).

2. 증상 식별

현상	진단
`bin/claude.exe` 크기가 ~1KB	postinstall 스크립트가 실행되지 않았거나, 바이너리가 교체되지 않음
`bin/claude.exe` 크기가 ~234MB	정상
`claude` 명령어 실행 오류 또는 비정상 종료 코드	추가 로그 확인 필요

빠른 확인 방법:

# Git Bash 또는 PowerShell에서 실행
ls -la "D:/node/nodejs/node_global/node_modules/@anthropic-ai/claude-code/bin/"

3. 주요 원인 분석 (빈도순)

3.1. 프라이빗 미러/국내 미러가 플랫폼 서브 패키지를 동기화하지 않음 ⭐ 가장 흔함

taobao 미러, tencent 미러, 회사 내부 저장소 등은 메인 패키지만 동기화하고 claude-code-win32-x64 서브 패키지는 동기화하지 않는 경우가 많습니다.
npm이 optional 패키지를 가져올 수 없으면 자동으로 건너뜁니다 (optional의 정의상 오류를 발생시키지 않음).
결과적으로 메인 패키지는 설치되지만, 스텁 파일이 교체되지 않습니다.

확인 방법:

npm config get registry
npm view @anthropic-ai/claude-code-win32-x64 version

두 번째 명령어에서 404 오류 또는 출력이 없으면 미러가 동기화되지 않은 것입니다.

3.2. `--ignore-scripts` 또는 관련 설정으로 라이프사이클 스크립트 비활성화

postinstall 스크립트가 실행되지 않으면, 플랫폼 패키지가 다운로드되어도 스텁 파일이 교체되지 않습니다.

확인 방법:

npm config get ignore-scripts

3.3. optional 의존성 비활성화 설정

.npmrc 파일에 omit=optional 또는 optional=false 설정
환경 변수 NPM_CONFIG_OMIT=optional
이전에 npm config set omit optional 실행 기록
--omit=optional, --no-optional, 또는 구형 npm의 --production 플래그 사용

확인 방법:

npm config get omit
npm config list

3.4. Node 아키텍처 불일치

64-bit Windows에서 32-bit Node를 실행하면 process.arch === 'ia32'가 되어 install.cjs의 PLATFORMS 목록과 일치하지 않아 Unsupported platform 오류가 발생합니다.

확인 방법:

# 반드시 win32-x64 또는 win32-arm64가 출력되어야 함
node -p "process.platform + '-' + process.arch"

3.5. npm 버전이 너무 오래됨

npm 7 이상부터 optionalDependencies의 플랫폼 필터링이 안정적으로 작동합니다.

확인 방법:

npm -v   # 10 이상 권장
node -v  # 메인 패키지 요구사항: >= 18

3.6. pnpm 또는 yarn 사용

pnpm의 구버전은 optional platform 패키지 처리에 문제가 있었고, yarn classic은 동작 방식이 다릅니다. 공식적으로 npm 사용을 권장합니다.

4. 진단 체크리스트 (한 번에 실행)

문제가 발생한 PC에서 다음 명령어들을 순서대로 실행하세요:

node -p "process.platform + '-' + process.arch"
node -v
npm -v
npm config get registry
npm config get omit
npm config get ignore-scripts
npm view @anthropic-ai/claude-code-win32-x64 version

출력 결과를 저장해두고 위의 원인 분석 섹션과 비교하여 문제를 진단하세요.

5. 해결 방법

방법 A: 표준 재설치 (90% 상황 해결) ⭐ 최우선 권장

npm uninstall -g @anthropic-ai/claude-code

npm i -g @anthropic-ai/claude-code \
  --include=optional \
  --foreground-scripts \
  --registry=https://registry.npmjs.org/ \
  --verbose

매개변수 설명

매개변수	역할
`-g`	글로벌 설치, 모든 디렉토리에서 명령어 사용 가능
`--include=optional`	optionalDependencies를 강제로 설치, 모든 비활성화 설정을 무시 (omit 목록 초기화 효과)
`--foreground-scripts`	`postinstall` 로그를 포그라운드에 출력, 실패 시 즉시 확인 가능, 스텁 파일이 남는 문제 방지
`--registry=https://registry.npmjs.org/`	이번 명령어만 공식 저장소 사용, 미동기된 미러 우회; 글로벌 config는 변경하지 않음
`--verbose`	HTTP 요청, tarball 다운로드, 스크립트 실행 과정을 모두 출력하여 디버깅에 용이

실행 시 postinstall 출력을 주의 깊게 확인하세요:

Native package ... not found 메시지가 없음 → 성공
Native package "@anthropic-ai/claude-code-win32-x64" not found 메시지 표시 → 방법 B 사용
Unsupported platform 메시지 표시 → 방법 D 사용

방법 B: 메인 패키지 + 플랫폼 패키지 수동 설치

미러 동기화 문제에 대한 대비책:

npm i -g @anthropic-ai/claude-code @anthropic-ai/claude-code-win32-x64 \
  --registry=https://registry.npmjs.org/

방법 C: postinstall 스크립트 수동 실행

메인 패키지 파일은 모두 있지만 bin/claude.exe가 여전히 스텁 파일인 경우:

cd "D:\node\nodejs\node_global\node_modules\@anthropic-ai\claude-code"
node install.cjs

방법 D: Node 아키텍처 오류 수정

32-bit Node를 제거하고 https://nodejs.org/ 에서 Windows x64 LTS Installer를 다운로드하여 설치한 후, 방법 A를 다시 실행하세요.

방법 E: 다른 PC에서 바이너리 복사 (최후의 방법)

설치가 정상적으로 완료된 PC에서:

전체 디렉토리 압축: D:\node\nodejs\node_global\node_modules\@anthropic-ai\
새 PC의 동일한 경로에 압축 해제
D:\node\nodejs\node_global\ 디렉토리에 claude.cmd 파일이 있는지 확인 (npm cmd-shim). 없으면 수동으로 생성:

@echo off
"%~dp0\node_modules\@anthropic-ai\claude-code\bin\claude.exe" %*

6. 설치 성공 확인

ls -la "D:/node/nodejs/node_global/node_modules/@anthropic-ai/claude-code/bin/"
# claude.exe 파일 크기가 약 245,966,496 바이트 (~234MB)여야 함

claude --version

7. 실제 문제 해결 기록

증상: Windows 11 PC A는 정상 설치(234MB), PC B는 1KB 스텁 파일만 존재
원인 파악: PC B의 npm이 @anthropic-ai/claude-code-win32-x64 플랫폼 서브 패키지를 설치하지 못함
해결: 방법 A의 단일 명령어로 해결:
npm i -g @anthropic-ai/claude-code --include=optional --foreground-scripts --registry=https://registry.npmjs.org/ --verbose
핵심 인사이트:
1. 메인 패키지의 1KB claude.exe는 스텁 파일이며, 실제 바이너리는 postinstall 스크립트에 의해 교체됨
2. optional 의존성 설치 실패는 자동으로 무시되며, 메인 패키지 설치가 실패하지 않음
3. 미러 저장소가 서브 패키지를 동기화하지 않은 것이 가장 흔한 원인이며, 공식 저장소를 지정하면 즉시 해결됨

8. 추가 참고 사항

이 패턴은 Bun의 npm 패키지(bun 메인 패키지 + @oven/bun-* 플랫폼 패키지)와 완전히 동일하므로, 동일한 문제 해결 방법을 적용할 수 있습니다.
유사한 아키텍처를 가진 패키지(esbuild, swc, turbo, rollup의 네이티브 모듈 등)에서 "설치는 되었지만 실행되지 않는" 문제가 발생하면, 플랫폼 서브 패키지 다운로드 여부와 postinstall 스크립트 실행 여부를 먼저 확인하는 것이 핵심입니다.

태그: npm Claude Code Windows 11 Node.js optionalDependencies

8월 8일 11:56에 게시됨

괴물 클럽

Claude Code Windows 설치 오류: npm 글로벌 설치 문제 해결 완벽 가이드

문제 상황 개요

핵심 의문점

환경 정보

빠른 결론

1. 패키지 아키텍처 이해

설치 과정

2. 증상 식별

3. 주요 원인 분석 (빈도순)

3.1. 프라이빗 미러/국내 미러가 플랫폼 서브 패키지를 동기화하지 않음 ⭐ 가장 흔함

3.2. `--ignore-scripts` 또는 관련 설정으로 라이프사이클 스크립트 비활성화

3.3. optional 의존성 비활성화 설정

3.4. Node 아키텍처 불일치

3.5. npm 버전이 너무 오래됨

3.6. pnpm 또는 yarn 사용

4. 진단 체크리스트 (한 번에 실행)

5. 해결 방법

방법 A: 표준 재설치 (90% 상황 해결) ⭐ 최우선 권장

매개변수 설명

방법 B: 메인 패키지 + 플랫폼 패키지 수동 설치

방법 C: postinstall 스크립트 수동 실행

방법 D: Node 아키텍처 오류 수정

방법 E: 다른 PC에서 바이너리 복사 (최후의 방법)

6. 설치 성공 확인

7. 실제 문제 해결 기록

8. 추가 참고 사항

인기 태그

괴물 클럽

Claude Code Windows 설치 오류: npm 글로벌 설치 문제 해결 완벽 가이드

문제 상황 개요

핵심 의문점

환경 정보

빠른 결론

1. 패키지 아키텍처 이해

설치 과정

2. 증상 식별

3. 주요 원인 분석 (빈도순)

3.1. 프라이빗 미러/국내 미러가 플랫폼 서브 패키지를 동기화하지 않음 ⭐ 가장 흔함

3.2. --ignore-scripts 또는 관련 설정으로 라이프사이클 스크립트 비활성화

3.3. optional 의존성 비활성화 설정

3.4. Node 아키텍처 불일치

3.5. npm 버전이 너무 오래됨

3.6. pnpm 또는 yarn 사용

4. 진단 체크리스트 (한 번에 실행)

5. 해결 방법

방법 A: 표준 재설치 (90% 상황 해결) ⭐ 최우선 권장

매개변수 설명

방법 B: 메인 패키지 + 플랫폼 패키지 수동 설치

방법 C: postinstall 스크립트 수동 실행

방법 D: Node 아키텍처 오류 수정

방법 E: 다른 PC에서 바이너리 복사 (최후의 방법)

6. 설치 성공 확인

7. 실제 문제 해결 기록

8. 추가 참고 사항

인기 태그

3.2. `--ignore-scripts` 또는 관련 설정으로 라이프사이클 스크립트 비활성화