pnpm 설치는 끝났는데 네이티브 패키지가 동작하지 않는 이유

pnpm의 파일 준비와 빌드 실행을 나눠 읽기 위한 도식입니다.

node_modules에는 패키지가 있는데 앱을 켜면 실행 파일이나 네이티브 모듈을 찾지 못합니다. 이런 경우에는 설치 로그에서 빌드 스크립트가 실행됐는지부터 찾아보세요. 무시된 빌드 스크립트와 패키지 호환성 문제를 구분하고, 사용 버전에 맞는 승인 정책으로 필요한 패키지만 검토하세요.

pnpm은 의존성을 받아 연결하는 작업과 의존성이 제공한 코드를 실행하는 작업을 구분합니다. 패키지에 따라 설치 스크립트가 바이너리를 준비하거나 네이티브 코드를 빌드합니다. 이 단계가 빠지면 JavaScript 진입 파일은 있어도 그 파일이 불러올 산출물은 없을 수 있습니다.

아래는 2026년 9월 28일 확인한 pnpm 12.x 문서를 기준으로 한 진단 순서입니다. sample-native-addon은 구조를 설명하기 위한 가상 패키지이며, 특정 패키지의 설치 결과나 승인 추천을 뜻하지 않습니다.

실패한 컴퓨터에서 버전과 차단 목록부터 읽습니다

로컬에서는 되고 CI에서만 안 된다면 로컬 설정부터 바꾸기 쉽습니다. 우선 오류가 난 환경의 터미널이나 CI 로그에서 다음 정보를 확보합니다.

pnpm --version
node --version
pnpm ignored-builds

ignored-builds는 빌드가 차단된 패키지를 보여 줍니다. 가상 모듈이 여기에 나온다면 설치 당시 스크립트가 실행되지 않은 경로부터 조사할 수 있습니다. 목록에 없다면 앱이 출력한 오류와 설치 로그를 이어서 봅니다. pnpm ignored-builds

예를 들어 필요한 .node 파일 자체가 없는 경우와, 파일은 있지만 현재 Node에서 로드할 수 없는 경우는 후속 작업이 다릅니다. 전자는 산출물 생성 과정을 확인해야 하고, 후자는 OS·CPU 아키텍처·Node 버전 등 패키지가 지원하는 환경을 대조해야 합니다. 모든 로딩 오류를 승인 누락으로 처리하면 설정은 바뀌는데 증상은 남습니다.

패키지 이름만 적어 두면 다음 설치 때 같은 문제를 비교하기도 어렵습니다. 잠금 파일의 정확한 패키지 버전, pnpm 버전, Node 버전, 실패한 명령을 함께 남겨 두면 로컬과 CI의 차이를 좁힐 수 있습니다.

지금 문서의 기본값은 설치 실패입니다

오래된 글에서 “설치는 성공하고 경고만 나온다”는 설명을 봤더라도 현재 프로젝트에 바로 적용하면 안 됩니다. pnpm 12.x 문서의 strictDepBuilds 기본값은 true입니다. 아직 검토하지 않은 의존성 빌드가 있으면 설치 명령이 0이 아닌 종료 코드로 끝납니다.

strictDepBuilds: false인 환경에서는 경고만 남길 수 있습니다. 한편 정책에 false로 명시해 거부한 패키지는 아직 판단하지 않은 패키지와 구별됩니다. 설치가 끝났다는 사실만으로 모든 스크립트가 허용됐다고 읽을 수 없는 이유입니다. 빌드 정책과 기본 처리

가상 프로젝트가 CI에서 설치 성공을 표시하면서 모듈을 못 찾는다면, 순서대로 확인할 곳이 생깁니다. 먼저 실제 pnpm 버전이 12.x인지 봅니다. 그다음 pnpm-workspace.yaml의 정책과 CI 명령에 스크립트를 건너뛰는 옵션이 있는지 확인합니다. ignoreScripts는 프로젝트와 의존성에 정의된 스크립트 실행을 막는 설정이므로 패키지별 승인만 바꿔서는 기대한 결과가 나오지 않을 수 있습니다.

이 확인 전에 strictDepBuilds를 끄면 진단에 필요한 실패 신호를 없애게 됩니다. 설치 명령이 무엇을 생략했는지 설명할 수 있을 때 설정 변경을 결정하는 편이 낫습니다.

검토한 버전의 스크립트만 허용합니다

현재 정책의 중심은 pnpm-workspace.yaml의 allowBuilds입니다. 매처마다 true 또는 false를 적어 실행을 허용하거나 거부합니다. 문법을 설명하는 가상 예시는 다음과 같습니다.

allowBuilds:
  sample-native-addon@1.2.0: true
  sample-optional-helper: false

첫 줄은 검토한 특정 버전을 허용합니다. 패키지 이름만 적는 것보다 적용 범위가 좁습니다. 두 번째 항목은 그 패키지의 스크립트를 실행하지 않겠다는 결정입니다. allowBuilds 설정

이 파일을 고치기 전에 해당 버전의 package.json과 설치 스크립트를 읽습니다. 어떤 파일을 만들고, 추가 다운로드를 하는지, 프로젝트가 실제로 그 기능을 사용하는지 확인할 대상입니다. 패키지 전체를 감사했다고 선언하려는 작업이 아니라, 이번 설치에서 허용할 실행을 판단하기 위한 검토입니다.

특히 Git이나 tarball에서 받은 의존성은 레지스트리 패키지 이름만으로 출처가 정해지지 않습니다. 공식 문서도 이런 의존성의 승인을 별도로 다룹니다. URL·커밋을 확인하지 않은 상태에서 이름 하나를 광범위하게 허용하는 예제를 가져오지 마세요.

approve-builds를 실행한 뒤에는 diff를 읽습니다

검토를 마쳤다면 pnpm approve-builds의 대화형 목록에서 필요한 패키지를 선택할 수 있습니다. 현재 문서는 승인과 거부를 allowBuilds에 기록한다고 안내합니다. 모든 대기 항목을 한 번에 허용하는 옵션도 있지만, 여기서는 원인을 좁힌 한 패키지만 대상으로 삼습니다.

예전 프로젝트를 옮겼다면 정책 파일의 변화도 읽어야 합니다. pnpm 11에서는 onlyBuiltDependencies와 ignoredBuiltDependencies 같은 이전 설정을 allowBuilds로 대체했습니다. 최신 approve-builds는 남아 있던 이전 항목을 정리할 수 있으므로, 예상한 승인 한 줄 외의 변경도 확인합니다. approve-builds 동작과 이전 설정 정리

또한 12.4.0부터는 승인 대기가 없는 이름에도 결정을 미리 기록할 수 있습니다. 이때 아직 설치되지 않았거나 대기 중이 아닌 패키지는 재빌드하지 않습니다. true가 파일에 생겼다는 것만으로 바이너리가 생긴 것은 아닙니다.

가상 모듈의 경우 정책 diff에서 sample-native-addon@1.2.0이 의도한 범위로 허용됐는지 확인하고, 이어지는 설치·빌드 로그에서 실제 대상이 처리됐는지 봅니다. 수동으로 파일만 수정했다면 해당 버전과 프로젝트 절차에 맞춰 설치 또는 재빌드를 다시 수행해야 합니다.

마지막 확인은 패키지를 쓰는 명령으로 합니다

설치 로그에서 빌드가 끝났다면 처음 실패한 앱 명령으로 돌아갑니다. 이때도 같은 오류가 나면 메시지가 달라졌는지 확인합니다. 파일 누락이 사라지고 지원하지 않는 바이너리 오류가 나온다면, 다음 조사 대상은 빌드 승인보다 실행 환경입니다.

CI에도 수정한 정책 파일이 전달됐는지 확인해야 합니다. 개발자 컴퓨터에서만 승인한 뒤 이전 파일로 CI를 돌리면 같은 실패가 반복될 수 있습니다. CI 로그의 pnpm·Node 버전과 실제 체크아웃한 정책을 로컬에서 확인한 값과 대조합니다.

문제를 닫을 때는 “설치 성공” 한 줄 대신, 차단됐던 패키지와 버전, 변경한 승인 범위, 빌드가 끝난 로그, 처음 실패했던 명령의 결과를 묶어 남기면 됩니다. 나중에 패키지 버전을 올렸을 때 무엇을 다시 검토해야 하는지까지 알 수 있습니다.