Yarn 4로 마이그레이션

원문 보기 위키 갱신 2026.10.07

Yarn 4로 마이그레이션 (Migration to Yarn 4)

@backstage/create-app으로 만든 Backstage 프로젝트는 이제 Yarn 4를 사용합니다. 여전히 Yarn 1을 사용하는 이전 버전의 Backstage가 있을 수 있으며, 이 튜토리얼이 마이그레이션을 도와줄 것입니다.

출처: 문서

본문

마이그레이션 (Migration)

이 가이드 외에도 Yarn 마이그레이션 가이드도 확인하세요.

무시 파일 업데이트 (Ignore File Updates)

먼저 앱에 업데이트된 무시 항목이 있는지 확인하세요. 이 항목은 새로 생성된 모든 프로젝트에 포함되지만, 여러분의 프로젝트에는 없을 수도 있습니다.

.gitignore에 다음을 추가하세요.

# Yarn files.pnp.*.yarn/*!.yarn/patches!.yarn/plugins!.yarn/releases!.yarn/sdks!.yarn/versions

그리고 .dockerignore에 다음을 추가하세요.

.yarn/cache.yarn/install-state.gz

설치 (Installation)

실제 설치로 넘어가 봅시다. 대부분의 단계를 별도의 Git 커밋으로 나눠서 만들 것을 권장합니다. 문제가 생겨 디버깅해야 할 때 돌아가기 쉽기 때문입니다. Yarn 4를 설치하려면 프로젝트 루트에서 다음 명령을 실행하세요.

yarn set version 4.x

note

위 명령이 작동하지 않으면 yarn set version latest를 실행해야 할 수도 있지만, Yarn 4를 넘어선 버전으로 이동할 수 있으므로 주의해서 사용하세요.

나중에 Yarn 워크스페이스 도구 플러그인이 필요하므로 그것도 설치하겠습니다.

yarn plugin import @yarnpkg/plugin-workspace-tools

이제 모든 의존성을 다시 설치할 준비가 되었습니다. 그러면 yarn.lock이 업데이트되고 프로젝트가 Yarn 노드 링커로 node-modules를 사용하도록 전환됩니다.

.yarnrc가 있다면 지금 삭제할 수 있지만, 옵션은 .yarnrc.yml로 옮기는 것을 잊지 마세요. 전체 옵션 목록은 Yarn 구성 문서를 참조하세요. 예를 들어 registry는 이제 npmRegistryServer, network-timeout은 httpTimeout입니다.

사용 방식 마이그레이션 (Migrate Usage)

이 시점에서 Yarn 4가 완전히 설정되었습니다! 남은 것은 Yarn 사용 방식을 마이그레이션 가이드에 따라 옮기는 것입니다. 예를 들어 yarn install --frozen-lockfile 명령은 yarn install --immutable로 바꿔야 합니다.

또한 Yarn 4 설치를 이미지에 복사하는 지침을 추가하도록 모든 Dockerfile을 업데이트해야 합니다.

COPY .yarn ./.yarnCOPY .yarnrc.yml ./

멀티 스테이지 Dockerfile에서는 yarn 명령을 실행하는 각 스테이지에도 Yarn 4 설치가 필요합니다. 예를 들어 마지막 스테이지에서 다음을 추가해야 할 수 있습니다.

COPY --from=build --chown=node:node /app/.yarn ./.yarnCOPY --from=build --chown=node:node /app/.yarnrc.yml  ./

Yarn 4에서 yarn install의 --production 플래그가 제거되었습니다. 대신 yarn workspaces focus --all --production을 사용해 프로덕션 배포에서 개발 의존성 설치를 피해야 합니다. 이 절충안으로 yarn workspaces focus는 --immutable 플래그를 지원하지 않습니다.

RUN yarn workspaces focus --all --production && rm -rf "$(yarn cache clean)"

추가로 yarn config는 임의의 키-값 쌍을 저장할 수 있던 방식에서 소수의 미리 정의된 쌍만 지원하도록 재작업되었습니다. 이전에는 node-gyp와 관련된 문제를 해결하기 위해 선호하는 python3 인터프리터를 설정했으므로, 적절한 대체 방법을 제공해야 합니다.

# Set Python interpreter for `node-gyp` to useENV PYTHON=/usr/bin/python3# Install sqlite3 dependencies. You can skip this if you don't use sqlite3 in the image,# in which case you should also move better-sqlite3 to "devDependencies" in package.json.RUN apt-get update && \    apt-get install -y --no-install-recommends libsqlite3-dev python3 build-essential && \    rm -rf /var/lib/apt/lists/* && \    yarn config set python /usr/bin/python3    rm -rf /var/lib/apt/lists/*

PYTHON 환경 변수는 Yarn이 호출되는 어떤 인스턴스보다도 비교적 일찍 선언되도록 하세요. 일부 모듈이 설치 중에 간접적으로 node-gyp를 트리거하기 때문입니다.

프로젝트에 package.json의 "bin" 항목으로 노출된 내부 CLI 도구가 있다면, 이 패키지들을 프로젝트 루트 package.json에 의존성으로 추가해야 합니다. 이는 Yarn이 실행 파일을 인식해 yarn <executable>을 통해 사용할 수 있게 하기 위함입니다.

Yarn 4로 마이그레이션