우선 폐쇄망 / 인트라넷 / 내부망 쓰는데 가지마 제발 이렇게 된 거 일단 원초적으로 살아남아보자. 에이전트없는

팀에서 개발환경을 공유한다는 것

mac os(linux) 환경에서 개발이 익숙하다보니, windows에서도 wsl ubuntu 환경을 조성해놨다. 과거 windows를 사용했을 때 path 설정의 악몽을 더 이상 겪고 싶지 않았다.

개발환경 팀원 : windows / powershell 나 : linux / wsl

이 개발 서버가 문제가 되리라곤 생각하지 못했다.

npm install을 때리면 우리가 모르는 사이에 마법처럼 모든 것이 설치되고 완벽하게 실행된다.

우리는... 나는 인터넷이 없는 환경에서 개발해보지 않았다.

문제

npm i 가 안된다는 것을 알고 우린 2가지 방법을 고민했다.

1. node_modules를 git으로 공유하자.
2. npm_package를 공유해서 install 환경을 만들자.

우선을 1번을 진행했고, 큰 문제를 마주했다.

아래의 상황을 겪고, 결국 windows와 linux 환경에서 모두 실행환경을 구현했다.

🚨 문제 발생: "Failed to load SWC binary"

내부망 Linux 서버에서 Next.js 개발 서버를 실행하려던 순간 마주한 에러:

npm run dev

⚠ Attempted to load @next/swc-linux-x64-gnu, but it was not installed
⚠ [TypeError: fetch failed] { [cause]: [AggregateError: ] { code: 'ETIMEDOUT' } }
⨯ Failed to load SWC binary for linux/x64

상황 정리:

• Windows 환경에서 개발한 Next.js 15 프로젝트
• Linux 내부망 서버로 이동 후 실행 실패
• 외부 인터넷 접근 불가 / 오프라인 (air-gapped 환경)
• SWC 바이너리가 런타임에 다운로드를 시도하지만 네트워크 차단

📖 발단: 플랫폼별 바이너리의 함정

Next.js SWC의 동작 원리

Next.js 12부터 도입된 SWC(Speedy Web Compiler)는 Rust로 작성된 고성능 컴파일러입니다. 하지만 여기에 함정이 있었습니다:

플랫폼별 네이티브 바이너리가 필요

@next/swc-win32-x64-msvc      # Windows용
@next/swc-linux-x64-gnu       # Linux용 (glibc)
@next/swc-darwin-arm64        # macOS M1/M2용

문제의 핵심

• Windows 개발 환경: Windows용 바이너리만 설치됨
• Linux 배포 환경: Linux용 바이너리가 없어서 런타임 다운로드 시도
• 폐쇄망: 다운로드 불가능으로 실행 실패

🔧 시도한 방법들: 가설과 실험

시도 1: Babel로 우회하기

// .babelrc
{
  "presets": ["next/babel"]
}

결과: SWC를 건너뛰고 Babel 사용 성공 문제점: 성능 저하, 근본적 해결이 아님

시도 2: dependencies 강제 설치

{
  "dependencies": {
    "@next/swc-linux-x64-gnu": "15.0.0"
  }
}

결과:

npm error code EBADPLATFORM
npm error notsup Unsupported platform for @next/swc-linux-x64-gnu

깨달음: npm은 플랫폼 체크로 다른 OS용 바이너리 설치를 막음

시도 3: npm 오프라인 캐시

npm install --cache ./.npm-offline-cache

결과: 현재 플랫폼용만 캐싱됨 한계: 멀티 플랫폼 지원 불가

✅ 해결책: yarn offline mirror

yarn vs npm의 결정적 차이점

npm의 한계:

• 플랫폼 체크가 엄격함
• optionalDependencies도 현재 플랫폼만 설치
• 강제 설치 옵션 없음

yarn의 장점:

• offline mirror가 모든 플랫폼의 .tgz 파일을 다운로드
• 실행 시 현재 플랫폼에 맞는 바이너리만 선택 사용

구현 단계

1단계: yarn offline mirror 설정

# .yarnrc
yarn-offline-mirror "./npm-packages-offline-cache"
yarn-offline-mirror-pruning true

2단계: package.json 수정

{
  "packageManager": "yarn@1.22.22",
  "optionalDependencies": {
    "@next/swc-win32-x64-msvc": "15.0.0",
    "@next/swc-linux-x64-gnu": "15.0.0"
  }
}

3단계: 외부망에서 캐시 생성

yarn install
ls npm-packages-offline-cache/ | grep swc
# @next-swc-linux-x64-gnu-15.0.0.tgz ✅
# @next-swc-win32-x64-msvc-15.0.0.tgz ✅

4단계: 내부망에서 오프라인 설치

git clone <repository>
yarn install --offline
yarn dev # 🎉 성공!

🎯 핵심 통찰: 패키지 관리자의 철학

npm의 철학: "정확성 우선"

• 플랫폼 호환성 엄격 검증
• 불필요한 파일 다운로드 방지
• 보안과 일관성 중시

yarn의 철학: "개발자 편의성 우선"

• offline mirror로 모든 의존성 사전 준비
• 개발자가 원하는 것을 유연하게 지원
• 폐쇄망 환경까지 고려한 설계

📊 성과 측정

Before (문제 상황)

❌ Linux 서버에서 Next.js 실행 불가
❌ 매번 Babel 우회 필요 (성능 저하)
❌ CI/CD 파이프라인 불안정

After (해결 후)

✅ Windows/Linux 모든 환경에서 동일하게 실행
✅ SWC 성능 최적화 유지
✅ 완전한 오프라인 빌드 가능
✅ Git 저장소 크기 최적화 (node_modules 제거)

🔍 개발자로서의 성찰

1. 문제 정의의 중요성

처음엔 "단순한 패키지 설치 문제"로 봤지만, 실제론:

• 플랫폼별 바이너리 호환성 문제
• 패키지 매니저별 설계 철학 차이
• 폐쇄망 환경의 특수성

교훈: 다양한 개발환경을 고려하자. next 고맙다...

2. 도구 선택의 기준

npm vs yarn 선택에서 고려사항:

• 기술적 요구사항: 멀티 플랫폼 지원
• 환경적 제약: 폐쇄망, 오프라인
• 팀 워크플로우: 기존 사용 패턴

교훈: 도구는 문제를 해결하는 수단, 맹신하지 말자

3. 지속가능한 해결책

단순한 workaround가 아닌 구조적 개선:

• .gitignore로 node_modules 제거
• offline mirror로 의존성 관리 표준화
• README 문서화로 팀 공유

교훈: 안되면 되게 하라

🚀 결론 및 actionable insights

폐쇄망 환경 개발의 핵심 원칙

1. 의존성 사전 준비: 모든 외부 의존성을 미리 캐싱
2. 멀티 플랫폼 고려: 개발/배포 환경이 다를 수 있음을 가정
3. 도구의 철학 이해: npm vs yarn vs pnpm의 차이점 숙지
4. 문서화 필수: 팀원이 동일한 환경을 재현할 수 있도록

다른 개발자들을 위한 체크리스트

# 프로젝트 시작 시
□ 배포 환경의 네트워크 제약 확인
□ 플랫폼별 바이너리 의존성 파악  
□ 적절한 패키지 매니저 선택
□ offline-first 전략 수립

# 문제 해결 시
□ 에러 메시지의 근본 원인 분석
□ 여러 도구/방법 비교 검토
□ 임시방편 vs 근본 해결 구분
□ 해결 과정 문서화 및 공유

개발은 문제 해결의 연. 오늘의 Failed to load SWC binary 에러가 yarn offline mirror라는 새로운 도구를 배우는 계기가 되었고, 폐쇄망 환경에서의 개발 노하우를 한층 더 쌓을 수 있었습니다.

여러분도 비슷한 문제를 겪고 계신다면, 이 해결 과정이 도움이 되길 바랍니다. 🎯

나중 배포시에도 이런 문제가 나올 수 있기때문에 지금해결 해두는게 낫다.

"The best error message is the one you learn the most from." - 오늘의 교훈

다시 결론 폐쇄망 가지마