---

name: pf-build-fix description: Turborepo 빌드 에러 해결. "빌드 에러", "build 실패", "turbo 에러" 요청 시 사용. allowed-tools: Read, Bash, Glob, Grep

PF 빌드 에러 해결 전문가

$ARGUMENTS 빌드 에러를 분석하고 해결합니다.

---

진단 프로세스

1단계: 에러 유형 파악

# 전체 빌드 로그 확인
pnpm build 2>&1 | head -100

# 특정 패키지만 빌드
pnpm --filter @pf-dev/ui build

2단계: 일반적인 에러 패턴

---

🔴 TypeScript 에러

타입 불일치

error TS2322: Type 'string' is not assignable to type 'number'

해결:

1. 해당 파일의 타입 정의 확인
2. Props 인터페이스와 실제 사용 비교
3. tsconfig.json의 strict 설정 확인

모듈 찾을 수 없음

error TS2307: Cannot find module '@pf-dev/ui' or its corresponding type declarations

해결:

# 1. 의존성 재설치
pnpm install

# 2. 패키지 빌드 순서 확인
pnpm --filter @pf-dev/ui build

# 3. tsconfig의 paths 확인
cat tsconfig.json | grep -A 10 "paths"

noUncheckedIndexedAccess 에러

error TS18048: 'items[0]' is possibly 'undefined'

해결:

// ❌ 에러
const first = items[0];
first.name;

// ✅ 해결
const first = items[0];
if (first) {
  first.name;
}

// 또는
const first = items.at(0);

---

🔴 Turborepo 에러

캐시 문제

error: could not find output "dist" in cache

해결:

# 캐시 삭제
pnpm clean

# 또는
rm -rf node_modules/.cache/turbo

의존성 순서 문제

@pf-dev/ui:build: error: Cannot find module '@pf-dev/api'

해결:

// turbo.json
{
  "tasks": {
    "build": {
      "dependsOn": ["^build"]  // 의존 패키지 먼저 빌드
    }
  }
}

순환 의존성

Circular dependency detected

해결:

1. pnpm why 패키지명으로 의존성 트리 확인
2. 공통 타입을 별도 패키지로 분리
3. 인터페이스와 구현 분리

---

🔴 Vite 에러

환경변수 누락

Uncaught ReferenceError: process is not defined

해결:

// vite.config.ts
export default defineConfig({
  define: {
    'process.env': {}
  }
});

외부 패키지 번들링 문제

[vite]: Rollup failed to resolve import "cesium"

해결:

// vite.config.ts
export default defineConfig({
  optimizeDeps: {
    include: ['cesium']
  },
  build: {
    commonjsOptions: {
      include: [/cesium/, /node_modules/]
    }
  }
});

---

🔴 pnpm/workspace 에러

catalog 버전 불일치

ERR_PNPM_SPEC_NOT_SUPPORTED_BY_ANY_RESOLVER  catalog: is not supported

해결:

# pnpm-workspace.yaml에 catalog 정의 확인
catalog:
  react: ^19.2.0

피어 의존성 경고

WARN  Issues with peer dependencies found

해결:

# .npmrc에 추가
auto-install-peers=true
strict-peer-dependencies=false

---

🔴 ESLint 에러

빌드 시 린트 에러로 실패

error  Unexpected any. Specify a different type  @typescript-eslint/no-explicit-any

해결 옵션:

# 1. 린트 무시하고 빌드 (임시)
pnpm build --no-lint

# 2. 해당 파일 수정
# 3. eslint-disable 주석 (최후의 수단)
// eslint-disable-next-line @typescript-eslint/no-explicit-any

---

빠른 해결 명령어

# 전체 초기화 (최후의 수단)
pnpm clean && rm -rf node_modules && pnpm install && pnpm build

# 특정 패키지만 재빌드
pnpm --filter @pf-dev/ui build --force

# 의존성 그래프 확인
pnpm turbo run build --graph

# 캐시 없이 빌드
pnpm turbo run build --force

---

에러 보고 시 포함할 정보

1. 전체 에러 메시지
2. 어떤 패키지/앱에서 발생했는지
3. 최근 변경사항
4. pnpm -v, node -v 버전