pnpm install 오류 해결: lockfile·workspace 점검 순서

pnpm install이 실패하면 무엇부터 확인하나요?

설치 로그의 첫 구체적인 오류를 기준으로 현재 폴더·실행 버전·workspace·lockfile을 확인합니다. 같은 설치 명령이 다시 통과하는지로 복구를 판단하며, lockfile 삭제를 첫 해결책으로 삼지 않습니다.

이 글의 기존 실행 검증 환경은 Windows · Node.js 24.19.0 · pnpm 11.19.0입니다. 자신의 프로젝트는 packageManager와 lockfile의 버전을 우선하세요. pnpm install 공식 옵션과 workspace 공식 문서에서 현재 동작을 확인할 수 있으며, 이번 문서 보강은 독자 프로젝트의 설치 성공을 대신 검증하지 않습니다.

pnpm install 실패는 모두 같은 원인이 아닙니다.

현재 경로 문제
pnpm 버전 불일치
workspace 설정 오류
package.json 문법 오류
lockfile 불일치
존재하지 않는 workspace 패키지
registry/network 문제
설치 script 문제
파일 권한 문제

오류 메시지의 첫 실패 지점을 확인한 뒤 범위를 좁힙니다.

1. 현재 폴더 확인

Windows PowerShell:

Get-Location
Get-ChildItem

macOS/Linux:

pwd
ls

다음 파일이 보이는지 확인합니다.

package.json
pnpm-workspace.yaml
pnpm-lock.yaml

workspace 루트가 아닌 apps/web 안에서 실행하고 있는지 확인합니다.

2. pnpm 버전 확인

pnpm -v
node -v

package.json도 확인합니다.

{
  "packageManager": "pnpm@11.19.0"
}

실제 실행 버전과 프로젝트 기준이 크게 다르면 같은 환경을 재현했다고 보기 어렵습니다.

3. pnpm-workspace.yaml 확인

packages:
  - "apps/*"

경로 패턴과 실제 폴더가 맞는지 확인합니다. labs의 실습은 각 패키지 매니저와 lockfile로 독립 관리하므로 메인 workspace에 포함하지 않습니다.

예를 들어 실제 폴더가 app/web인데 설정이 apps/*라면 해당 package가 workspace로 인식되지 않습니다.

4. 각 workspace의 package.json 확인

apps/web/package.json 예시:

{
  "name": "@taskflow/web",
  "private": true,
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "lint": "eslint ."
  }
}

filter 이름과 package name이 일치해야 합니다.

pnpm --filter @taskflow/web dev

5. lockfile을 무조건 삭제하지 않기

pnpm-lock.yaml에는 실제 의존성 해석 결과가 저장됩니다.

install이 실패했다고 바로 삭제하면 문제의 원인이 package.json 변경인지 lockfile 충돌인지 구분하기 어려워질 수 있습니다.

Git을 사용한다면 먼저 변경 상태를 확인합니다.

git status
git diff -- pnpm-lock.yaml

다른 브랜치의 lockfile 변경이 섞였는지 확인합니다.

6. frozen lockfile 오류

CI나 엄격한 설치 설정에서는 package.json과 lockfile이 일치하지 않으면 실패할 수 있습니다.

핵심은 “lockfile을 없애서 통과”가 아니라 package.json 변경과 lockfile 변경이 같은 의도인지 확인하는 것입니다.

로컬에서 정상적으로 lockfile을 갱신한 뒤 저장소에 함께 반영합니다.

7. workspace 의존성 확인

workspace 패키지를 참조하는 프로젝트에서는 로컬 패키지가 실제로 존재하는지 확인합니다.

예:

{
  "dependencies": {
    "@taskflow/shared": "workspace:*"
  }
}

그런데 packages/shared 또는 해당 name의 workspace가 없다면 설치가 실패할 수 있습니다.

workspace:* 사용
→ 실제 workspace 존재 확인
→ package.json name 확인
→ pnpm-workspace.yaml 포함 여부 확인

8. registry와 network는 별도 문제

패키지를 찾지 못하거나 다운로드에 실패하는 경우 workspace와 다른 범주일 수 있습니다.

pnpm config get registry

회사 네트워크, 프록시, 사설 registry를 사용하는 경우 해당 설정을 확인합니다.

인증 토큰이 포함된 설정을 본문이나 로그에 그대로 공유하지 않습니다.

9. 설치 script 오류 확인

패키지를 내려받는 단계는 성공했지만 postinstall이나 native build script가 실패할 수도 있습니다.

이 경우 “pnpm install 실패”라는 결과만 보고 lockfile을 수정하면 안 됩니다.

로그에서 실패한 script 이름과 패키지를 먼저 찾습니다. pnpm의 의존성 build script 승인 정책에 의해 실행이 차단된 경우도 구분합니다. 필요한 script와 정확한 패키지 버전을 검토한 뒤 해당 lab 범위에서만 허용합니다. 예제 Storybook lab은 esbuild@0.28.2만 allowBuilds로 허용하며, 모든 패키지 script를 일괄 허용하지 않습니다.

• pnpm build script 설정: https://pnpm.io/settings/build#allowbuilds

10. 캐시와 node_modules 정리는 마지막

설정과 의존성 상태가 맞는데 로컬 설치 결과가 손상된 정황이 있을 때 정리를 고려합니다.

Windows PowerShell 예시:

Remove-Item -Recurse -Force node_modules
pnpm install

하지만 이 단계 전에 반드시 원인을 확인합니다.

pnpm store 자체를 지우는 작업은 더 넓은 영향을 주므로 근거 없이 반복하지 않습니다.

오류 해결 체크리스트

현재 workspace 루트인가
Node.js 버전 확인
pnpm 버전 확인
packageManager 확인
pnpm-workspace.yaml 확인
workspace package name 확인
package.json 변경 확인
pnpm-lock.yaml diff 확인
registry/network 확인
install script 첫 실패 확인
필요할 때만 node_modules 정리
같은 명령으로 재검증

자주 발생하는 실수

lockfile부터 삭제합니다

원인과 변경 이력을 먼저 확인합니다.

workspace root와 app 폴더를 혼동합니다

Get-Location 또는 pwd로 현재 위치를 확인합니다.

npm과 pnpm을 섞습니다

TaskFlow 루트에서는 pnpm만 사용합니다.

오류 로그의 마지막 줄만 봅니다

실제 원인은 더 앞의 첫 실패 지점에 있을 수 있습니다.

학습 완료 체크리스트

• pnpm install 오류를 설정·workspace·network·script 문제로 구분할 수 있습니다.
• packageManager와 실제 pnpm 버전을 비교할 수 있습니다.
• pnpm-workspace.yaml과 실제 폴더 구조를 비교할 수 있습니다.
• lockfile을 삭제하기 전에 diff를 확인합니다.
• workspace:* 참조가 실제 패키지와 연결되는지 확인할 수 있습니다.
• clean install 후 dev와 lint까지 검증합니다.

독립 실습: workspace 누락 원인 분리

작은 workspace 전체 파일을 별도 폴더에 준비한 뒤 아래 순서로 비교합니다. 프로젝트 앱은 필요하지 않습니다.

pnpm install
pnpm --filter @practice/hello hello

정상 상태에서는 workspace connected가 출력됩니다. pnpm-workspace.yaml의 apps/*를 app/*로 바꾼 사본에서 같은 filter 명령을 실행하면 일치하는 프로젝트가 없다는 진단을 볼 수 있습니다. 실제 폴더는 apps/hello이므로 패턴을 apps/*로 복구하고 pnpm install 뒤 같은 명령을 다시 실행합니다. 이 경우에는 registry 변경이나 lockfile 삭제가 해결책이 아닙니다. lockfile 불일치는 별도의 문제이며 아래 진단 절에서 첫 오류와 manifest 변경을 비교합니다.

변형 과제: 패키지 폴더 이름과 package.json의 name을 각각 다르게 바꾸었을 때 workspace 패턴 문제와 filter 이름 문제를 어떻게 구분할지 설명합니다.

package.json
pnpm-workspace.yaml
pnpm-lock.yaml
apps/web
labs/*

pnpm install
pnpm --filter @taskflow/web dev
pnpm --filter @taskflow/web lint

dev-env-step-06-npm-eresolve-fixed

workspace 진단 순서 문서화
packageManager 기준 확인
lockfile diff 확인 절차 추가
clean install 검증 절차 추가

package.json
pnpm-workspace.yaml
pnpm-lock.yaml
docs/development-environment.md

pnpm install
pnpm --filter @taskflow/web dev
pnpm --filter @taskflow/web lint

dev-env-step-07-pnpm-recovery

node_modules/
dist/
storybook-static/
.env.local
.env.*.local

VITE_API_URL=https://api.example.invalid
VITE_APP_NAME=TaskFlow

import js from '@eslint/js';
import { defineConfig } from 'eslint/config';
import globals from 'globals';

export default defineConfig([
  { ignores: ['dist/**'] },
  js.configs.recommended,
  {
    files: ['src/**/*.js'],
    languageOptions: { globals: globals.browser },
    rules: { 'no-console': 'warn' },
  },
]);

<!doctype html>
<html lang="ko">
<head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>TaskFlow 개발환경</title></head>
<body><main id="app"></main><script type="module" src="/src/main.js"></script></body>
</html>

{
  "name": "@taskflow/web",
  "private": true,
  "type": "module",
  "scripts": {
    "dev": "vite --host 127.0.0.1",
    "build": "vite build",
    "lint": "eslint ."
  },
  "devDependencies": {
    "vite": "8.3.0",
    "eslint": "10.11.0",
    "@eslint/js": "10.0.1",
    "globals": "17.12.0"
  }
}

const apiUrl = import.meta.env.VITE_API_URL;
const appName = import.meta.env.VITE_APP_NAME;

if (!apiUrl) {
  throw new Error('VITE_API_URL 환경 변수가 필요합니다.');
}

export const env = {
  apiUrl,
  appName: appName || 'TaskFlow',
};

import './style.css';
import { env } from './config/env.js';

const app = document.querySelector('#app');
const title = document.createElement('h1');
title.textContent = env.appName;
const status = document.createElement('p');
status.textContent = '개발환경 스타터가 실행 중입니다.';
const api = document.createElement('p');
api.id = 'api-url';
api.textContent = `API URL: ${env.apiUrl}`;
app.append(title, status, api);

body { margin: 0; color: #202020; background: #f6f6f6; font: 16px/1.6 system-ui, sans-serif; }
main { max-width: 720px; margin: 64px auto; padding: 24px; }
h1 { font-size: 30px; font-weight: 500; }
p { overflow-wrap: anywhere; }

# TaskFlow 개발환경

이 스타터는 개발환경 진단을 위한 최소 Vite/vanilla JavaScript 앱입니다. 할 일 관리 기능이나 API 서버는 포함하지 않습니다.

Node.js 24.19.0, pnpm 11.19.0으로 검증했습니다. 루트는 pnpm만 사용하며 apps/*만 workspace입니다. labs의 npm/Yarn/pnpm 실습은 독립 프로젝트입니다.

## 2회차

메인 앱은 pnpm을 유지합니다. labs/yarn-modern은 독립 Yarn 실습입니다.

## 3회차

apps/web/.env.example을 apps/web/.env.local로 복사합니다. .invalid 주소는 표시만 하며 실제 API 호출은 하지 않습니다. 공개 샘플값만 제공하고 로컬 파일은 ZIP에서 제외합니다.

## 4회차

Vite 루트는 apps/web입니다. env.js가 필수 VITE_API_URL을 검사하고 화면에 공개 URL을 표시합니다.

## 5회차

ESLint 설정과 의존성은 apps/web에 있습니다. 루트 pnpm lint가 앱의 eslint .을 호출합니다.

## 6회차

npm ERESOLVE 실습은 labs/npm-eresolve에서 실행합니다. 최종본은 react와 react-dom 19.3.0 호환 조합입니다.

## 7회차

설치 오류는 경로 → Node/pnpm 버전 → workspace → package.json → lockfile 순으로 확인합니다. 새 폴더에서 pnpm install --frozen-lockfile로 재현합니다.

{
  "name": "taskflow",
  "private": true,
  "packageManager": "pnpm@11.19.0",
  "engines": {
    "node": ">=24"
  },
  "scripts": {
    "dev": "pnpm --filter @taskflow/web dev",
    "build": "pnpm --filter @taskflow/web build",
    "lint": "pnpm --filter @taskflow/web lint"
  }
}

packages:
  - "apps/*"

# TaskFlow 개발환경 07 완료 체크포인트

Node.js 24.19.0 / pnpm 11.19.0 검증 기준입니다. pnpm을 별도로 설치한 환경에서 실행하세요. ZIP에는 node_modules, dist, 로컬 환경 변수, 실제 비밀값이 없습니다.

1. 이 폴더에서 `pnpm install --frozen-lockfile`
2. PowerShell: `Copy-Item apps/web/.env.example apps/web/.env.local` 또는 macOS/Linux: `cp apps/web/.env.example apps/web/.env.local`
3. `pnpm dev` 후 http://127.0.0.1:5173 확인
4. `pnpm build`
5. `pnpm lint`

apps/web가 Vite 루트입니다. 환경 변수도 이 폴더에 둡니다. 표시용 API 주소에 실제 요청을 보내지 않습니다. labs는 메인 workspace에서 제외되어 각 폴더에서 별도 설치합니다.

원문 단계별 전체 파일과 실행 검증 범위는 docs/development-environment.md를 확인하세요.

nodeLinker: node-modules

{
  "name": "taskflow-yarn-lab",
  "private": true,
  "type": "module",
  "packageManager": "yarn@4.18.0",
  "scripts": {
    "dev": "node src/main.js",
    "lint": "node --check src/main.js"
  }
}

console.log('TaskFlow Yarn 독립 실습');

{
  "name": "taskflow-npm-eresolve",
  "private": true,
  "type": "module",
  "packageManager": "npm@11.16.0",
  "scripts": {
    "test": "node verify.mjs"
  },
  "dependencies": {
    "react": "19.3.0",
    "react-dom": "19.3.0"
  }
}

# npm ERESOLVE 실습

이 폴더에서만 npm을 사용합니다.

오류 재현: `npm install react@18.3.1 react-dom@19.3.0 --save-exact`

복구: `npm install react@19.3.0 react-dom@19.3.0 --save-exact`

검증: `npm ls react react-dom`, `npm test`

react-dom 19.3.0의 peerDependencies는 react ^19.3.0입니다. 최종 package.json은 복구된 상태입니다.

import { createElement } from 'react';
import { renderToString } from 'react-dom/server';
import assert from 'node:assert/strict';
const html = renderToString(createElement('p', null, 'TaskFlow'));
assert.equal(html, '<p>TaskFlow</p>');
console.log('React 서버 렌더링 통과');

다음 학습

다음 글부터는 선택 도구 문제를 다룹니다.

먼저 Tailwind CSS의 Unknown at rule 경고를 재현하고, 실제 빌드 실패와 VS Code 에디터 경고를 구분합니다.

다음 글: Tailwind CSS Unknown at rule 경고 해결: VS Code와 PostCSS 설정 확인

공식 문서

• pnpm: https://pnpm.io/
• pnpm workspaces: https://pnpm.io/workspaces