새 맥북 개발 환경 세팅: git clone이 가져오지 않는 것들

맥북을 새로 받고 하던 프로젝트를 이어서 하려 했습니다. 리포를 클론하고 npm install 을 돌린 다음 개발 서버를 띄웠는데, 브라우저에 이게 떴습니다.

Module not found: Can't resolve '@/generated/prisma/client'
  1 | import { PrismaPg } from "@prisma/adapter-pg";
> 2 | import { PrismaClient } from "@/generated/prisma/client";

저는 처음에 코드가 깨진 줄 알았습니다. 경로 별칭 설정이 잘못됐거나, 누가 파일을 지우고 커밋했거나. 그런데 이 리포는 며칠 전 컴퓨터에서 멀쩡히 돌던 것이고 그 사이 아무도 손대지 않았습니다.

같은 커밋, 같은 코드인데 한쪽에서만 안 됩니다. 그러면 문제는 코드가 아니라 코드 밖에 있습니다.

없던 것은 코드가 아니라 생성물

원인은 .gitignore 한 줄이었습니다.

/src/generated

이 프로젝트는 Prisma 클라이언트를 src/generated/prisma 로 뽑아 쓰는데, 그건 스키마에서 만들어 내는 산출물이라 커밋하지 않습니다. 옛 컴퓨터에는 언젠가 prisma generate 를 돌린 결과가 남아 있었습니다. 새 컴퓨터에는 없습니다. npm install 은 이걸 만들어 주지 않습니다.

npm run db:generate    # prisma generate

한 줄로 끝났습니다. 문제는 이걸 알아내는 데 걸린 시간이 아니라, 에러 메시지가 원인을 전혀 가리키지 않았다는 점입니다. Module not found 는 import 문제처럼 읽힙니다. 실제로는 빌드 파이프라인의 한 단계를 건너뛴 것이었습니다.

다른 프로젝트에서 또 난 같은 일

Expo 앱 쪽으로 넘어가니 비슷한 게 또 있었습니다. ios/ 와 android/ 디렉터리가 통째로 없었습니다.

이것도 의도된 것이었습니다. Expo 의 CNG(Continuous Native Generation) 방식은 네이티브 프로젝트를 설정 파일에서 매번 새로 만들어 쓰고, 그래서 .gitignore 에 들어가 있습니다.

npx expo prebuild --platform ios

패턴이 같습니다. 리포에는 만드는 방법만 들어 있고 만든 결과는 안 들어 있습니다. 옛 컴퓨터에서 안 겪은 이유는 그 결과물이 이미 거기 있었기 때문이지, 그 컴퓨터가 특별해서가 아니었습니다.

있는데 안 보이는 도구

iOS 빌드를 걸려니 이번엔 다르게 막혔습니다.

$ xcodebuild -version
xcodebuild: error: ...

$ swift --version
Apple Swift version 6.3.3

Swift 는 답하는데 xcodebuild 는 없다고 합니다. Xcode 를 App Store 에서 이미 받아 뒀는데도 그랬습니다. 원인은 macOS 의 활성 개발자 디렉터리 설정이 Xcode 가 아니라 Command Line Tools 를 가리키고 있던 것이었고, 이건 따로 글로 정리했습니다.

여기서 얻은 건 분류 하나입니다. "없는 것"과 "안 보이는 것"은 증상이 비슷한데 고치는 방법이 전혀 다릅니다. 앞의 둘은 명령을 돌려 만들어 내면 되고, 이건 설정을 고쳐야 합니다. 없는 줄 알고 재설치를 시작하면 시간만 버립니다.

리포가 알려주지 않는 시스템 패키지

node_modules 는 package.json 이 목록을 들고 있습니다. 리포를 클론하면 무엇이 필요한지 알 수 있고, 명령 하나로 다 받습니다.

시스템 쪽은 그런 게 없습니다. 이번에 없어서 막힌 것들입니다.

필요한 것	증상	리포에 목록이 있나
CocoaPods	iOS prebuild 가 Pod 설치 단계에서 멈춤	없음
JDK	Unable to locate a Java Runtime	없음
Android SDK	ANDROID_HOME 미설정, adb 없음	없음

CocoaPods 는 brew install cocoapods 로 1.17.0 을 받아 해결됐습니다. Android 쪽은 JDK 와 SDK 와 환경변수까지 세 겹이라 아직 손대지 않았습니다.

이건 리포의 잘못이 아닙니다. 이 도구들은 프로젝트에 속한 게 아니라 머신에 속합니다. 다만 그래서 어디에도 적혀 있지 않습니다. 옛 컴퓨터의 이 목록은 몇 달에 걸쳐 필요할 때마다 하나씩 깔면서 만들어진 것이고, 만든 사람조차 전체 목록을 모릅니다.

리포에 있지만 열쇠가 없던 비밀

가장 오래 막힌 건 이쪽입니다.

이 프로젝트는 환경변수를 암호화해서 리포에 커밋합니다. 값이 전부 암호문이라 커밋해도 안전하고, 복호화 개인키만 따로 보관합니다. 그래서 클론하면 설정 파일 38개 키가 통째로 따라옵니다. 읽을 수만 없을 뿐입니다.

열쇠는 비밀번호 관리자에 있었습니다. 옛 컴퓨터에는 그 파일이 이미 있었으니 몇 달 동안 그 존재를 잊고 지냈습니다.

계정 로그인도 같은 종류입니다. 클라우드 빌드를 걸려니 이렇게 나왔습니다.

$ npx eas-cli whoami
Not logged in

설정도 프로젝트 ID도 전부 리포에 들어 있어서 준비는 끝나 있는데, 로그인 하나가 없어서 아무것도 안 됩니다. Xcode 의 Apple 계정도 마찬가지고요.

비슷한 증상, 네 종류의 원인

정리하고 보니 막힌 것 전부가 네 갈래로 갈렸습니다.

종류	이번에 걸린 것	고치는 방법
생성물	node_modules, Prisma 클라이언트, ios/	명령을 돌려 만든다
머신 전역 설정	활성 개발자 디렉터리	설정을 고친다
시스템 패키지	CocoaPods, JDK, Android SDK	설치한다
비밀과 계정	복호화 개인키, 빌드 서비스 로그인, Apple 계정	다른 곳에서 가져온다

위에서 아래로 갈수록 리포가 도와주는 정도가 줄어듭니다. 첫 줄은 리포가 방법까지 들고 있고, 둘째 줄은 증상조차 오해를 부르고, 셋째 줄은 목록이 아예 없고, 마지막 줄은 리포 안에 있으면 안 되는 것들입니다.

새 컴퓨터가 느리게 느껴지는 이유가 이겁니다. 마지막 두 줄은 검색해서 나오는 게 아니라 기억해 내야 합니다.

다음 맥에서 다르게 할 것

이번에 겪고 나서 하나는 확실해졌습니다. 옛 컴퓨터가 "다 되던" 상태였던 게 아니라, 몇 달치 설치와 로그인이 쌓여 있던 것뿐입니다. 그 목록은 아무 데도 없었고 새 기계에서 하나씩 다시 부딪히며 복원됐습니다.

그래서 리포에 셋업 문서를 하나 두려고 합니다. 클론 직후에 돌려야 하는 명령, 필요한 시스템 패키지, 어떤 계정에 로그인해야 하는지. 특히 세 번째가 중요합니다. 이번에 빌드 서비스 계정이 리포의 GitHub 계정과 다르다는 걸 다시 확인하느라 문서를 뒤져야 했습니다.

다만 이 문서가 실제로 유지될지는 확신이 없습니다. 새 기계를 세팅하는 일은 몇 년에 한 번이라 문서가 낡을 시간이 충분하고, 실제로 이 프로젝트의 배포 문서는 이미 낡아 있었습니다. 여섯 항목을 "아직 안 함"으로 적어 뒀는데 그중 다섯은 진작 끝나 있었습니다. 낡은 체크리스트는 없는 것보다 나쁠 수도 있습니다.

지금으로선 자동으로 검증되는 것만 문서에 적는 쪽이 낫겠다고 생각하고 있습니다. 사람이 지켜야만 최신인 목록은 결국 안 지켜집니다.