ERR_PACKAGE_PATH_NOT_EXPORTED, exports, 서브경로 | 깊은 import만 막히면?
exports가 하위 경로를 닫으면 ERR_PACKAGE_PATH_NOT_EXPORTED가 납니다. 공개 진입점으로 바꾸거나 내 패키지에 서브경로를 열고, 모듈 없음과 ESM require를 가릅니다. 다시 설치해도 같은 맵이면 호출 경로를 고칩니다. Node.js, import, 패키지, 한국 1인 개발자. 2026년 9월 노드 패키지 진입점 문서.
ERR_PACKAGE_PATH_NOT_EXPORTED는 패키지가 없어서가 아니라, exports가 그 하위 경로를 열지 않아 노드가 import를 거절한 줄입니다. node_modules를 지우기 전에, 에러의 슬래시 뒤 경로를 exports 키와 대조하세요.
설치는 끝났고 파일도 있는데 한 줄만 빨간 경우가 많습니다. 깊은 내부 경로는 exports가 생긴 버전부터 막힙니다.
공개 진입점으로 바꾸거나, 내 패키지면 그 서브경로를 한 줄 추가하세요. 모듈 없음, ESM을 require로 부른 에러와 문장이 다릅니다. 기준은 Node.js 패키지 진입점 문서입니다.
폴더는 있는데 그 경로만 닫힌다
패키지 폴더는 있는데, 슬래시 뒤 경로만 닫혀 있습니다.
노드 12.7부터 패키지는 exports로 바깥에 열 입구를 직접 적습니다. 이 필드가 있으면, 적히지 않은 하위 경로는 캡슐 안에 남고 패키지 이름으로는 불러올 수 없습니다. 공식 문서는 require('pkg/subpath.js')가 ERR_PACKAGE_PATH_NOT_EXPORTED를 던진다고 적습니다. 디스크의 파일이 지워진 것이 아닙니다.
에러 문장은 보통 이렇게 생깁니다. 패키지 이름, 요청한 서브경로, 그리고 그 경로가 exports에 없다는 설명입니다. 슬래시 앞은 설치된 패키지이고, 슬래시 뒤가 거절된 문입니다. 깊은 경로를 지우고 패키지가 공개한 이름만 남기면 같은 파일이라도 통과하는 경우가 많습니다.
절대 경로로 node_modules 안 파일을 직접 가리키면 노드가 예외로 읽어 주기도 합니다. 문서가 말하는 약한 캡슐입니다. 번들러와 다음 버전 업데이트는 그 구멍을 약속하지 않으니, 고치는 방법으로 쓰지 않는 편이 낫습니다.
먼저 볼 한 줄 | 에러의 슬래시 뒤를 복사해 그 패키지 package.json의 exports 키와 나란히 두세요. 키가 없으면 공개 입구가 아닙니다.
폴더는 열려 있어도, exports에 없는 옆 문은 패키지 이름으로는 통과하지 않는다
exports가 여는 문
메인만 적어도 나머지 경로는 전부 닫힙니다.
문자 하나인 "exports": "./main.js"는 패키지 루트만 엽니다. 객체로 쓰면 점(".")이 루트이고, "./theme" 같은 키가 서브경로입니다. 소비자는 ui-kit/theme처럼 키와 같은 경로만 부를 수 있습니다. ui-kit/dist/theme.js처럼 파일 위치를 그대로 적으면, 그 문자열이 키에 없을 때 같은 에러가 납니다.
조건부 exports는 입구를 더 나눕니다. import와 require, types가 서로 다른 파일을 가리킬 수 있습니다. 타입 선언만 있고 런타임 키가 없으면 편집기는 조용한데 노드만 거절합니다. 개발 서버가 초록이어도 node script.js가 빨간 이유가 여기인 경우가 있습니다.
공개된 서브경로와 거절되는 깊은 경로
// ui-kit/package.json
{
"exports": {
".": "./dist/index.js",
"./theme": "./dist/theme.js"
}
}
import theme from 'ui-kit/theme'; // 키가 있으니 통과
import hidden from 'ui-kit/dist/theme.js'; // ERR_PACKAGE_PATH_NOT_EXPORTED
비슷한 세 문장을 가르는 표
문장 앞머리만 봐도 다음 행동이 갈립니다.
문장
의미
먼저 할 일
Cannot find module
패키지 이름 또는 파일이 해석 경로에 없음
설치, 대소문자, 작업 폴더
ERR_REQUIRE_ESM
패키지는 있는데 CJS require가 ESM을 부름
import로 바꾸거나 동적 import
ERR_PACKAGE_PATH_NOT_EXPORTED
패키지는 있고, 그 서브경로만 비공개
exports에 있는 키로 경로 수정
세 문장을 한 명령으로 밀면 시간이 늘뿐입니다. 모듈 없음은 설치와 경로 대소문자 문제이고, ESM require는 모듈 형식 문제이며, 이번 코드는 공개 입구 문제입니다. 한국에서 넥스트와 노드 스크립트를 같이 돌리는 1인 개발자라면, 페이지는 번들러가 깊은 경로를 풀어 주고 크론 스크립트만 노드 규칙으로 거절하는 장면을 자주 만납니다.
의존성을 지웠다가 다시 설치해도 exports 맵은 그대로입니다. 락파일 버전이 깊은 경로를 쓰던 예전 코드와 맞지 않으면, 설치가 초록이어도 다음 실행에서 같은 줄이 납니다.
고치는 순서
호출부를 먼저 고치고, 남 패키지의 exports는 건드리지 않습니다.
1단계는 에러에 나온 패키지 폴더의 package.json을 엽니다. exports의 키를 읽고, 내 소스의 import가 그 키와 같은지 봅니다. 점, ./theme, "./features/*" 같은 와일드카드면 별이 받는 한 조각만 허용됩니다. 와일드카드 밖의 private 폴더는 여전히 거절됩니다.
2단계는 호출을 공개 키로 바꿉니다. 체인지로그에 "deep import 제거"가 있으면 메이저 업데이트의 의도된 변화입니다. 내부 파일을 계속 부르기 위해 의존성 package.json을 손으로 고치면, 다음 설치가 그 수정을 덮습니다.
3단계는 정말 그 파일만 필요할 때입니다. 패치 도구로 내 저장소에 서브경로 키를 추가하거나, 패키지 작성자에게 공개 입구를 요청합니다. node_modules 파일을 통째로 복사해 상대 경로로 두는 방법은 라이선스와 업데이트를 함께 떠안습니다.
라이브러리를 한국 팀 저장소에 올려 두고 앱이 @my/kit/theme를 부른다면, 게시된 exports에 그 키가 있어야 합니다. 빌드 결과 파일이 dist에 있어도 키를 안 적으면 소비자는 같은 에러를 봅니다. 타입만 따로 열 때는 types 조건을 런타임 파일과 짝으로 둡니다.
열지 않을 파일은 키에 넣지 않습니다. 테스트 헬퍼와 내부 유틸을 공개하면 다음 리팩터마다 메이저가 됩니다. 노드 문서는 이 캡슐이 세미버 업그레이드 때 공개 인터페이스를 지키려는 장치라고 설명합니다.
