25장. 실습 환경을 같은 상태로 맞춘다

입문 실습이 가장 자주 실패하는 이유는 코드보다 환경 차이다. 저장소 루트에 .nvmrc 또는 toolchain 파일, packageManager, lockfile을 두고 CI와 로컬이 같은 Node·npm을 쓰게 한다. npm ci가 실패하면 lockfile을 지우지 말고 package.json과 lockfile이 왜 어긋났는지 diff부터 본다. npm run build는 개발 서버가 숨겨 준 type·server/client 경계 오류를 찾는 첫 관문이다.

환경변수는 .env.example에 이름과 형식만 기록한다. NEXT_PUBLIC_ 값은 브라우저 번들에 들어가므로 secret에 붙이지 않는다. LocalLoop에는 DATABASE_URL, AUTH_ISSUER, AUTH_CLIENT_ID, AUTH_CLIENT_SECRET, APP_BASE_URL, OBJECT_BUCKET이 필요하다. 시작 script는 필수 값 누락을 즉시 실패시키고 실제 값은 출력하지 않는다.

첫날의 완료 조건은 화면이 한 번 뜨는 것이 아니다. 새 폴더에 clone한 독자가 README 순서대로 install, test, build, start, health 요청을 모두 재현하고, 오류가 나면 명령·환경·원문 로그를 실습 기록에 남기는 것이다.