문제 상황

: web을 turbo의 remote cache활용할 경우 CI환경에서 빌드 에러가 발생한다.

• 상황 파악
  • 최근에 Remote Cache 설정을 했다. 이게 문제의 원인인 듯하다. 위 이미지에서도 “Remote Cache enabled”라고 적혀있는걸로 보아, Remote Cache를 사용했다.

원인

• 에러 메시지를 살펴보면, /home/runner/../@img/sharp-darwin-arm64를 찾고 있다. @img/sharp-darwin-arm64은 MacOS 64-bit ARM을 위해 미리 빌드한 sharp이다. 그런데 CI 환경은 Linux환경으로, 이 파일을 읽지 못한다.
  • 그렇다면 OS에 맞지 않는 @img/sharp-darwin-arm가 CI환경에 존재하는 이유는 뭘까? → 위에서 Remote Cache를 설정해서이다. MacOS환경인 로컬에서 빌드할 때 @img/sharp-darwin-arm가 생성이 되었고, 이 결과물을 Remote환경에 캐싱하고, CI환경에서는 이 파일을 로드한 것이다.

해결 방법

• web만 빌드 OFF

  // turbo.json
  "web#build": {
    "cache": false
  }
  

  • 문제점: 로컬 빌드에서도 캐싱이 안된다.

• 환경에 따른 다른 환경 변수를 사용해 캐싱을 한다.

  // turbo.jsonc
  "@web-memo/web#build": {
  	"env": ["TURBO_CACHE_PLATFORM"]
  },
  

  // package.json
  "build:web": "TURBO_CACHE_PLATFORM=$(uname -s) turbo build --filter=@web-memo/web",
  

  • uname -s : 현재 os 이름을 출력하는 명령어. Mac: Darwin, Linux: Linux

    즉, turbo build를 실행하는데 TURBO_CACHE_PLATFORM=OS환경 를 환경 변수로 설정하고 실행하는 것이다.

  • darwin: 애플에서 만든 오픈 소스 유닉스 컴퓨터 OS

추가 내용

• CI 환경 내에서는 @actions/cache@4를 이용해 .next/cache를 캐싱해서 사용하고 있다.

  - name: Cache Next.js build
    uses: actions/cache@v4
    with:
      path: |
        apps/web/.next/cache
      key: ${{ runner.os }}-nextjs-${{ hashFiles('**/pnpm-lock.yaml', 'apps/web/next.config.mjs') }}
      restore-keys: |
        ${{ runner.os }}-nextjs-
  

  • 주로 webpack/turbopack의 컴파일 캐시, 이미지 최적화 캐시, ISR 페이지 캐시 등이 저장된다.
  • 단, patform-specific한 native binary를 포함하지 않는다. sharp 같은 바이너리는 node_modules쪽에 있다.

• .next폴더가 output으로 설정되어 캐싱이 되었는데, 에러 메시지에는 node_modules를 가리키는 이유 : .next 빌드 산출물 안에 native binary의 절대 경로가 기록되어있기 떄문

  • Next.js는 빌드 시 .next/server/ 하위에 .nft.json(Node File Trace)파일을 생성하는데, 여기에 해당 페이지/라우트가 런타임에 필요로 하는 파일들의 경로가 기록된다. Mac에서 빌드하면 이 trace 파일 안에 node_modules/.pnpm/[email protected]/node_modules/@img/sharp-darwin-arm64 같은 경로가 들어가게 된다.