pnpm 12.14.0 모노레포 CI 설치와 캐시 점검 가이드
pnpm 12.14.0의 변경 사항을 기준으로 모노레포 CI의 빌드 캐시 제외 대상, 설치 대기, 락파일 재사용과 스토어 재업로드를 점검한다.
2026-10-23
설치가 느릴 때 빌드와 대기를 나눠 본다
추가로 설치할 것이 없는 pnpm install도 레지스트리의 일일 업데이트 체크 때문에 수 분을 기다릴 수 있었다. 연결은 받아 놓고 응답하지 않는 레지스트리에서 발생했던 문제다. 반대로 네이티브 애드온처럼 시스템 라이브러리에 의존하는 빌드는, 캐시가 있어도 그 결과를 재사용하지 않아야 할 수 있다.
이 글의 기준은 **pnpm v12.14.0 (2026-10-15)**이다. pnpm v12.14.0 릴리스 노트는 설치 과정의 불필요한 대기를 없애는 변경과, 빌드 결과의 재사용을 명시적으로 제한하는 설정을 함께 담고 있다.
모노레포 CI에 적용할 때는 전체 설치 시간만 비교하지 말고, 어떤 작업이 줄었는지 구분해서 확인하자. 업데이트 체크를 기다리는 시간, 의존성을 다시 해석하는 작업, git 의존성 조회, 변경 없는 스토어의 업로드는 각각 다른 변경 사항의 영향을 받는다. sideEffectsCache.exclude는 이와 별도로 빌드 재사용의 경계를 정한다.
아래 그림은 이번 변경을 CI에서 관찰할 지점과 연결한다.
캐시 키로 표현할 수 없는 빌드는 제외한다
sideEffectsCache.exclude는 빌드가 pnpm의 캐시 키에 포함할 수 없는 조건에 의존할 때 쓰는 설정이다. 릴리스 노트가 제시한 예는 네이티브 애드온이 링크하는 시스템 라이브러리다.
네이티브 애드온을 사용한다는 이유만으로 모두 제외하기보다는, 해당 패키지의 빌드가 어떤 외부 조건에 의존하는지 먼저 확인해야 한다. 판단 기준은 “빌드가 오래 걸리는가”가 아니라 “빌드 결과를 결정하는 조건을 캐시 키가 담을 수 있는가”다.
제외 목록에 들어간 패키지는 다음과 같이 처리된다.
- 각 프로젝트에서 빌드한다.
- 로컬 side-effects cache에서 빌드 결과를 복원하거나 저장하지 않는다.
remoteCache서버에서도 빌드 결과를 복원하거나 저장하지 않는다.
따라서 원격 캐시를 사용하더라도 제외 패키지의 빌드 결과를 공유하는 경로는 유지되지 않는다. 적용 후에는 해당 패키지가 프로젝트마다 빌드되는지를 확인 대상으로 삼아야 한다. 캐시 적중 여부만으로 정상 동작을 판단해서는 이 설정의 목적을 확인할 수 없다.
제외 항목은 minimumReleaseAgeExclude와 같은 패턴을 사용한다. 자료에 명시된 패턴은 다음과 같다.
| 패턴 | 지정 형태 | 제외 목록을 정할 때 확인할 것 |
|---|---|---|
name |
패키지 이름 | 이름으로 지정할 대상 |
@scope/* |
스코프 패턴 | 스코프 단위로 묶을 대상 |
name@version |
이름과 버전 | 버전까지 지정할 대상 |
전역 가상 스토어를 사용하는 경우에는 복사본의 경계도 달라진다. 제외 패키지뿐 아니라 그 패키지에 의존하는 패키지도 프로젝트마다 자체 복사본을 갖는다. 제외 대상을 검토할 때 해당 패키지만 보지 말고, 그것에 의존하는 패키지까지 확인해야 하는 이유다.
아래 그림은 제외 설정이 빌드 결과의 공유 경로와 프로젝트별 복사본에 미치는 영향을 구분한다.
업데이트 알림이 없어도 설치 결과와 분리해 판단한다
pnpm install과 pnpm add는 일일 업데이트 체크가 끝나기를 더 이상 기다리지 않는다. 명령이 먼저 끝나면 업데이트 알림을 생략하고, 다음번에 다시 체크한다.
여기서 바뀐 것은 업데이트 체크의 존재 여부가 아니라 명령 완료와의 관계다. CI 로그에 업데이트 알림이 보이지 않는다고 해서 체크가 영구적으로 꺼졌다고 해석하면 안 된다.
기존 CI에서 설치할 내용이 없는데도 명령 종료가 늦었다면, 적용 전후에 같은 조건의 설치를 비교해 볼 수 있다. 특히 릴리스 노트에 나온 “레지스트리가 연결을 수락한 뒤 응답하지 않는 상황”이 기존 증상과 맞는지 확인하자. 이 변경을 실제 패키지 다운로드나 빌드 시간의 개선으로 해석하지 않도록, 설치 작업이 끝난 뒤 남던 대기가 줄었는지를 관찰하는 편이 정확하다.
업데이트 체크의 종료 여부에 따른 알림 처리는 다음과 같다.
catalog와 부분 체크아웃은 락파일 보존을 확인한다
워크스페이스의 catalog에 선언된 항목이 모두 실제 의존성에서 참조되는 것은 아니다. 사용하지 않는 항목이 남아 있거나, 해당 패키지를 overrides 항목이 대체할 수 있다.
이런 워크스페이스에서는 이전에 의존성 해석이 일어날 때마다 모든 의존성을 레지스트리에서 다시 해석했다. 이번 버전에서는 pnpm install, pnpm add, pnpm update가 pnpm-lock.yaml을 재사용한다.
CI에 적용한 뒤에는 미사용 catalog 항목이 있는 워크스페이스를 확인 대상으로 잡자. 기존에 전체 의존성을 다시 해석하던 동작이 사라졌는지 살피면 된다. 다만 이 수정은 미사용 항목 때문에 발생하던 재해석에 관한 것이다. 모든 설치가 레지스트리를 사용하지 않는다는 뜻으로 확대해서는 안 된다.
부분 체크아웃을 사용하는 CI라면 별도의 보존 조건도 확인해야 한다. 자료에 제시된 필터 설치 형태는 다음과 같다.
pnpm install --filter <pkg>
이제 디스크에 없는 워크스페이스 프로젝트의 락파일 항목도 유지된다. sparse checkout처럼 일부 프로젝트만 내려받은 환경에서, 필터가 디스크에 존재하는 모든 프로젝트와 일치하더라도 없는 프로젝트의 항목을 지우지 않는다.
검토할 대상은 프로젝트의 importer만이 아니다. 해당 프로젝트와 관련된 packages와 catalog 항목도 보존 대상이다. 부분 체크아웃에서 설치한 뒤 락파일 차이를 확인할 때 이 범위를 함께 살펴야 한다.
락파일이 바뀌었다고 모두 회귀로 판단해서도 안 된다. 패키지가 어떤 의존성을 일반 의존성이면서 optional peer로도 선언한 경우, 이번 버전은 그 패키지에 도달하는 가장 얕은 경로를 기준으로 연결 방식을 결정한다. 기존 락파일에는 일반 의존성으로 기록되어 있더라도, 새로 추가한 의존성이 해당 peer를 제공하면 새 설치와 마찬가지로 peer로 기록할 수 있다.
이 조건에 해당하면 다음 설치에서 락파일 항목이 바뀔 수 있다. 적용 후 차이는 다음처럼 원인별로 읽는 편이 낫다.
| 상황 | 이번 버전의 동작 | 락파일 검토 지점 |
|---|---|---|
| 참조되지 않는 catalog 항목 존재 | 기존 락파일 재사용 | 미사용 항목 때문에 전체 재해석이 발생하는지 |
| 부분 체크아웃에서 필터 설치 | 디스크에 없는 프로젝트 항목 보존 | importers, packages, catalog 항목이 남는지 |
| 일반 의존성과 optional peer 선언이 겹침 | 가장 얕은 경로를 기준으로 연결 방식 결정 | 새 의존성이 peer를 제공하는 조건인지 |
git 조회와 스토어 업로드를 따로 측정한다
여러 워크스페이스 프로젝트가 같은 git 의존성을 사용한다면 브랜치나 태그 조회의 반복 여부를 확인하자. linkWorkspacePackages가 활성화된 환경에서는 이전에 프로젝트마다 git ls-remote를 실행했다. 이제 해당 git 의존성의 브랜치나 태그는 설치당 한 번 조회한다.
이 변경은 git 의존성이 있는 모노레포에 해당한다. 적용 전후 로그에서 비교할 것은 프로젝트 수에 따라 반복되던 조회다. 이를 모든 git 작업이 한 번만 실행된다는 의미로 넓히지 않아야 한다.
스토어 캐시에는 다른 변경이 적용된다. 설치가 스토어에 아무것도 추가하지 않으면 스토어 디렉터리의 수정 시간도 바꾸지 않는다. GitLab처럼 수정 시간을 확인하는 CI 캐시는 그 결과 변경 없는 스토어를 다시 업로드하지 않게 된다.
따라서 설치 명령의 실행 시간과 캐시 업로드 구간을 나눠 봐야 한다. 설치가 빨라졌는지만 확인하면 스토어 재업로드가 사라진 효과를 놓칠 수 있다. 반대로 스토어에 실제로 내용이 추가된 실행은 “변경 없는 스토어”를 검증하는 사례로 사용할 수 없다.
아래 그림은 스토어에 내용이 추가되지 않은 설치가 수정 시간 기반 캐시 업로드에 연결되는 조건을 보여 준다.
적용 후에는 작업이 줄었는지와 재사용 경계가 맞는지 확인한다
이번 버전의 CI 점검은 불필요한 작업이 사라졌는지 확인하는 일과, 재사용하면 안 되는 빌드가 실제로 분리되는지 확인하는 일로 나뉜다.
기존에 지연이 있던 작업에서는 설치할 내용이 없는 실행의 종료 시점, 미사용 catalog 항목이 있는 워크스페이스의 의존성 재해석, 공유 git 의존성의 조회 반복을 확인하자. 스토어 캐시는 아무것도 추가하지 않은 실행에서 재업로드가 발생하는지 따로 확인한다.
sideEffectsCache.exclude를 적용한 작업에서는 기대가 다르다. 제외 패키지는 각 프로젝트에서 빌드되어야 하며, 로컬과 원격 side-effects cache를 통한 복원·저장은 일어나지 않아야 한다. 전역 가상 스토어를 사용한다면 그 패키지에 의존하는 패키지까지 프로젝트별 복사본의 범위에 들어간다.
부분 체크아웃 작업은 설치 후 락파일에 디스크 밖 프로젝트의 항목이 남는지를 확인하고, optional peer 조건에 해당하는 차이는 별도로 검토한다. 전체 설치 시간이 줄었다는 결과만으로 끝내지 않고, 각 작업이 사라지거나 유지되어야 하는 이유까지 대조해야 이번 릴리스의 변경을 CI에 제대로 반영할 수 있다.