클라우드 Mac에서 Node.js 네이티브 모듈의 Apple Silicon 빌드 검증하기

개발 머신에서 로드되는 Node.js 네이티브 모듈이라고 해서 Apple Silicon 기반 클라우드 Mac에서도 안정적으로 배포할 수 있는 것은 아닙니다. 캐시에 남아 있는 사전 빌드 파일, 배포 패키지에서 누락된 빌드 산출물, 잘못된 동적 라이브러리 경로 때문에 npm install은 성공한 것처럼 보여도 깨끗한 머신에서 처음 require()를 실행할 때 실패할 수 있습니다. 더 신뢰할 수 있는 방법은 소스 재빌드, 바이너리 검사, 패키징 검사, 격리 설치를 하나의 검증 체계로 연결하는 것입니다.

먼저 검증 기준 고정하기

시작하기 전에 실행 환경부터 기록하고, 곧바로 캐시를 삭제한 뒤 재설치하지 마십시오. Node.js 네이티브 모듈은 N-API를 사용할 수도 있고 특정 모듈 ABI에 의존할 수도 있으며, 두 방식의 호환 범위는 서로 다릅니다. 프로젝트에서는 .nvmrc, .node-version 또는 CI 매개변수로 Node.js 메이저 버전을 고정하고 npm 버전도 로그에 함께 기록해야 합니다.

uname -m
sw_vers
node --version
npm --version
node -p "process.versions.napi || 'no-napi'"
node -p "process.versions.modules"
xcode-select -p
clang --version

Apple Silicon 환경에서는 uname -m이 arm64를 반환해야 합니다. 터미널 프로세스 자체가 다른 아키텍처에서 실행되고 있다면 이후의 빌드 결과는 대상 환경을 대표할 수 없습니다. 또한 시스템 업데이트 후 명령줄 도구가 예기치 않게 전환되는 일을 방지하려면 xcode-select -p가 의도한 툴체인을 가리키는지도 확인해야 합니다.

검증 대상은 “현재 디렉터리에서 실행되는가”가 아니라 “저장소의 소스 코드로 대상 아키텍처에 맞고 최종 배포 패키지에서 로드할 수 있는 산출물을 생성할 수 있는가”입니다.

깨끗한 작업 공간에서 소스 재빌드 강제하기

오랫동안 사용한 작업 디렉터리에서 배포 검증을 진행하지 마십시오. 먼저 지정된 커밋을 체크아웃한 다음 의존성 디렉터리와 모듈 자체의 빌드 디렉터리를 삭제합니다. 프로젝트가 설치 스크립트로 .node 파일을 생성한다면 전체 설치 로그를 반드시 보존해야 합니다.

git status --short
git rev-parse HEAD
rm -rf node_modules build
npm cache verify
npm ci
npm rebuild --build-from-source

npm cache verify는 캐시 구조만 검사하며, 빌드에서 캐시가 사용되지 않았다는 사실까지 입증하지는 않습니다. 따라서 핵심 단계는 여전히 --build-from-source입니다. 프로젝트에 명시적인 빌드 스크립트가 있다면 npm rebuild가 모든 생성 단계를 처리한다고 가정하지 말고 npm run build도 실행해야 합니다.

실패하면 먼저 전체 출력을 보존한 다음 Python, 컴파일러, SDK 경로와 헤더 파일을 확인하십시오. 오류가 발생할 때마다 모든 캐시를 삭제해서는 안 됩니다. 무차별적인 정리는 문제 현장을 훼손하며, 원인이 툴체인, 소스 코드, 설치 스크립트 중 어디에 있는지 판단하기도 어렵게 만듭니다.

N-API와 모듈 ABI 구분하기

N-API를 사용하는 모듈은 선언된 최소 N-API 버전을 기록하고 대상 Node.js 버전에서 로드 테스트를 실행해야 합니다. 모듈 ABI에 직접 의존하는 확장 모듈은 일반적으로 Node.js 메이저 버전별로 각각 빌드해야 하며, 한 버전에서 생성한 바이너리를 다른 버전으로 복사해 계속 사용할 수 없습니다.

Mach-O 아키텍처와 동적 의존성 검사하기

빌드가 끝나면 모든 네이티브 바이너리를 먼저 찾아야 합니다. 관례적인 경로에 있는 첫 번째 파일만 검사해서는 안 됩니다.

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  xargs -0 file

find . -type f -name '*.node' -not -path './node_modules/.cache/*' -print0 |
  while IFS= read -r -d '' binary; do
    echo "== $binary"
    lipo -info "$binary"
    otool -L "$binary"
  done

대상이 Apple Silicon이라면 배포되는 모든 .node 파일에 arm64가 포함되어야 합니다. 배포 범위가 두 아키텍처를 모두 포함한다고 명확히 정해진 경우에만 유니버설 바이너리를 생성해야 합니다. 형식만 갖추기 위해 동일한 수준으로 테스트하지 않은 두 슬라이스를 합치지 마십시오.

otool -L에서는 개발 머신의 절대 경로, 임시 디렉터리, 패키지에 포함되지 않은 사용자 정의 동적 라이브러리를 중점적으로 찾아야 합니다. 시스템 프레임워크 경로는 일반적으로 유지해도 되지만 개인 디렉터리나 빌드 작업 공간을 가리키는 참조는 배포 전에 수정해야 합니다. 모듈에 .dylib가 포함되어 있다면 해당 파일이 실제 패키징 목록에 들어 있는지, 이동 가능한 로드 경로를 사용하는지도 확인해야 합니다.

실제로 배포할 npm 패키지 검증하기

소스 디렉터리에서 직접 테스트를 실행하면 선언되지 않은 파일, 상대 경로, 남아 있는 산출물이 로드 과정에 관여할 수 있습니다. 배포 전에 먼저 tarball을 생성한 다음 빈 디렉터리에서 설치해야 합니다.

rm -rf .package-check
mkdir .package-check

npm pack --json > .package-check/pack.json
PACKAGE_FILE="$(node -e "
const fs=require('fs');
const data=JSON.parse(fs.readFileSync('.package-check/pack.json','utf8'));
process.stdout.write(data[0].filename);
")"

tar -tzf "$PACKAGE_FILE"
cd .package-check
npm init -y >/dev/null
npm install "../$PACKAGE_FILE"
node -e "const addon=require('your-module'); console.log(typeof addon)"

your-module을 실제 패키지 이름으로 바꾸고 마지막 줄을 최소한의 실제 기능 호출로 확장하십시오. 스모크 테스트에서는 JavaScript 진입점 파일의 존재만 확인하지 말고 네이티브 함수를 최소 한 번 호출해야 합니다. 모듈이 동기 및 비동기 인터페이스를 모두 제공한다면 각각 한 번씩 실행하고 프로세스 종료 코드도 확인해야 합니다.

tar -tzf 출력도 함께 검토하십시오. 라이선스, 타입 선언, JavaScript 진입점, 대상 .node 파일과 필요한 동적 라이브러리는 존재해야 하며, 소스 캐시, 테스트 자격 증명, 임시 로그, 로컬 설정은 패키지에 포함되어서는 안 됩니다.

자주 발생하는 오류를 배포 게이트로 전환하기

하나의 포괄적인 “빌드 실패”가 근본 원인을 가리지 않도록 검증을 서로 독립적인 실패 조건으로 나누는 것이 좋습니다.

1. 환경 게이트: 머신 아키텍처, Node.js, npm, N-API 또는 ABI가 선언된 조건과 일치하지 않으면 중단합니다.
2. 재빌드 게이트: 기존 산출물을 삭제한 후 소스 빌드가 성공하고 새로운 .node 파일이 생성되어야 합니다.
3. 아키텍처 게이트: 배포되는 모든 바이너리에 대상 arm64 슬라이스가 포함되어야 합니다.
4. 의존성 게이트: 작업 공간, 개인 디렉터리 또는 패키지에 포함되지 않은 동적 라이브러리를 참조해서는 안 됩니다.
5. 패키지 내용 게이트: 소스 디렉터리가 아니라 npm pack 결과를 기준으로 판단합니다.
6. 실행 게이트: 격리된 디렉터리에 tarball을 설치하고 네이티브 API를 최소 하나 호출합니다.

DPLYMAC에서 이 절차를 실행할 때는 각 작업의 환경 목록, 커밋 해시, tarball 체크섬, 스모크 테스트 출력을 하나의 빌드 증거로 함께 보관할 수 있습니다. 이렇게 하면 나중에 Node.js나 컴파일 도구를 업그레이드하더라도 차이가 환경, 컴파일 단계, 패키징 단계, 실행 단계 중 어디에서 발생했는지 판단할 수 있습니다.

최종 배포 기준은 단순해야 합니다. 깨끗한 체크아웃에서 재빌드할 수 있고, 바이너리 아키텍처가 올바르며, 동적 의존성을 다른 환경으로 이동할 수 있고, 배포 패키지 내용이 완전하며, 해당 배포 패키지가 격리된 환경에서 실제 호출을 완료할 수 있어야 합니다. 이 다섯 가지 조건을 모두 충족해야 네이티브 모듈이 Apple Silicon 검증을 통과한 것입니다.

자주 묻는 질문