잠금 파일

어제 되던 배포가 오늘 깨질 때 봐요. 부품마다 실제로 깔린 판 번호를 못 박아 둔 기록이고, 이 파일이 있어야 내 컴퓨터와 배포 서버가 같은 상태가 돼요.

쉽게 말하면

가게에 물건을 받을 때 종이가 두 장 생겨요. 하나는 발주서 예요. "종이컵 이 규격으로 적당히" 처럼 내가 원하는 것을 적은 종이죠. 다른 하나는 납품 명세서 예요. 그날 실제로 어느 공장에서 몇 번 규격 물건이 왔고 봉인 번호가 무엇인지, 들어온 물건 그대로 적힌 종이예요. 두 번째 지점을 첫 번째와 똑같이 차리려면 들고 가야 하는 건 발주서가 아니라 명세서예요. 잠금 파일이 그 명세서예요.

이름은 도구마다 달라요. npm 은 package-lock.json, yarn 은 yarn.lock, pnpm 은 pnpm-lock.yaml 을 만들어요. 생김새는 달라도 하는 일은 하나예요. 오늘 실제로 깔린 부품 구성을 그대로 기록해 두는 것 이에요.

이 문서는 부품을 받아 오는 도구 이야기를 하지 않아요. 그건 패키지 매니저 자리고, 여기는 그 도구가 남기는 기록 한 장만 파고들어요.

명세서가 없는 저장소

저장소 안 · 목록 파일: 있음(허용 범위만 적힘) · 잠금 파일: 없음 · 배포 서버: 설치할 때마다 새로 계산

코드가 똑같아도 설치하는 날짜마다 부품 구성이 달라요. 어제 되던 배포가 오늘 깨지고, 그 원인을 내 코드에서 찾느라 하루가 갑니다.

명세서가 있는 저장소

저장소 안 · 목록 파일: 있음 · 잠금 파일: 있음(부품마다 판 번호와 봉인 번호) · 배포 서버: 잠금 파일 그대로 설치

어제와 오늘이 같아요. 무엇이 달라졌는지 알고 싶으면 이 파일의 변경 내역만 보면 되고, 되돌릴 지점도 이 파일이에요.

파일 안에 실제로 적히는 것

잠금 파일을 열면 부품 이름마다 몇 줄이 붙어 있어요. 사장님이 알아야 할 항목은 네 개예요.

적히는 것	무슨 뜻인가	이것이 지켜 주는 것
정확한 판 번호	허용 범위가 아니라 그날 계산된 결과 하나예요. 1.4.2 처럼 딱 한 값이 적혀요	설치 날짜가 달라도 같은 판이 깔려요
받아 온 곳 주소	그 부품 파일을 어느 저장소에서 내려받았는지예요	회사 내부 저장소를 쓰는 경우, 엉뚱한 곳에서 받아 오는 일을 막아요
봉인 번호(무결성 값)	내려받은 파일의 내용을 계산해 나온 지문 같은 값이에요	같은 판 번호로 내용이 바뀐 파일이 오면 설치가 멈춰요. 조용히 다른 물건이 섞이는 것을 막아요
딸려 온 부품까지 전부	내가 고른 부품이 기대는 부품, 그것이 또 기대는 부품의 판 번호도 함께 적혀요	내가 이름도 모르는 깊은 곳의 부품까지 어제와 같아져요

이 파일은 사람이 손으로 고치는 파일이 아니에요

판 번호를 바꾸고 싶으면 목록 파일을 고치고 설치 명령을 다시 돌려요. 그러면 도구가 잠금 파일을 다시 계산해서 써 줘요. 손으로 한 줄만 고치면 봉인 번호가 안 맞아서 설치가 실패하거나, 더 나쁘게는 아무 일도 안 일어난 것처럼 보이다가 배포 서버에서 터져요.

그래서 잠금 파일은 읽는 파일 이에요. 사장님이 이 파일에서 얻을 것은 딱 하나, "오늘 우리 서비스의 부품 구성이 이것이다" 라는 기준선이에요.

없으면 이런 순서로 사고가 와요

잠금 파일이 없어서 나는 사고는 특징이 있어요. 원인과 증상 사이에 며칠이 비어 있어요. 그래서 순서를 미리 알아 두는 값이 커요.

1목록 파일에는 허용 범위만 적혀 있어요. "1.4.2 이상, 2.0.0 전까지" 같은 식이에요. 그날 무엇이 깔릴지는 설치하는 순간에 계산돼요.
2부품 제작자가 새 판을 올려요. 밤사이에 일어나는 일이고 내 저장소에는 아무 흔적이 없어요.
3배포가 돌면서 새로 계산해요. 코드는 그대로인데 어제와 다른 판이 깔려요. 여기까지는 아무 경고도 없어요.
4빌드가 실패하거나, 더 나쁘면 성공해요. 실패하면 그날 알지만, 성공하고 특정 화면만 조용히 망가지면 손님이 먼저 알아요.
5내 코드를 뒤져요. 안 고친 코드를 반나절 들여다보는 구간이에요. 여기서 시간이 가장 많이 새요.
6되돌릴 지점이 없다는 걸 알아요. 어제 무엇이 깔려 있었는지 적어 둔 곳이 없으니, 어제 상태로 못 돌아가요. 배포 되돌리기도 부품 구성까지는 못 되돌려요.

장면 1 · 배포를 맡은 개발자가 보고했다

“코드는 어제와 같은데 빌드만 실패해요. 서버에서 설치할 때 부품이 새로 계산되고 있어요.”

이 말을 들었을 때 물을 것은 하나예요. "잠금 파일이 저장소에 있나요, 그리고 배포 서버가 그 파일을 그대로 따르는 설치를 쓰나요." 둘 중 하나라도 아니면 오늘의 복구보다 이 둘을 갖추는 것이 이번 사고의 진짜 대응이에요. 다음 주에 같은 일이 또 오니까요.

확인해 보세요

3주 동안 코드를 한 줄도 안 고친 예약 사이트가 오늘 배포에서 실패했어요. 저장소에 잠금 파일이 없다는 걸 확인했다면, 지금 순서는?

갱신은 사건이에요

잠금 파일이 바뀌었다는 것은 내 서비스의 부품 구성이 바뀌었다는 뜻 이에요. 코드 한 줄 안 고쳐도 이 파일이 바뀌면 그날 배포는 어제와 다른 배포예요.

언제 바뀌나	일부러인가	사장님이 볼 것
부품을 새로 추가했어요	일부러예요	무엇이 왜 들어왔는지 한 줄 메모. 딸려 온 부품 수가 갑자기 크게 늘었는지
부품 판을 올렸어요	일부러예요	올린 부품이 몇 개인지. 하나씩 올렸는지, 한꺼번에 올렸는지
새로 계산하는 설치 명령을 그냥 돌렸어요	얼떨결이에요	이 경우가 가장 흔해요. 의도 없이 수십 줄이 바뀌어 있으면 원래대로 되돌리고 다시 시작해요
도구를 바꿨어요	보통 얼떨결이에요	잠금 파일이 두 장 생겼는지. 두 장은 서로 다른 판을 가리켜요
누가 손으로 고쳤어요	사고예요	봉인 번호가 안 맞을 수 있어요. 되돌리고 도구로 다시 만들어요

잠금 파일 변경은 코드 검토 대상이에요

이 파일은 줄 수가 많아서 검토에서 그냥 넘기기 쉬워요. 넘기지 말고 두 가지만 봐요. 첫째, 내가 이번에 손댄 부품 말고 다른 이름이 바뀌었나. 둘째, 판 번호 앞자리가 올라간 것이 있나. 둘 중 하나라도 있으면 이번 배포에는 확인 한 바퀴가 더 필요해요. 검토 방법은 코드 검토에 있어요.

갱신 자체를 겁낼 필요는 없어요. 겁낼 것은 의도 없는 갱신 이에요. 부품 판을 언제 올릴지 결정하는 이야기는 남이 만든 부품(라이브러리)와 판을 움직이지 않기 쪽에 있어요.

둘 이상이 같이 고칠 때

사람이 둘로 늘면 잠금 파일에서 충돌이 나요. 각자 다른 부품을 넣고 각자 계산했으니, 같은 자리에 서로 다른 내용이 적힌 거예요.

1충돌 난 잠금 파일을 손으로 합치지 않아요. 줄 단위로 짜맞추면 어느 쪽도 아닌 제3의 구성이 만들어져요. 가장 흔한 사고예요.
2목록 파일 쪽 충돌을 먼저 정리해요. 어느 부품을 어느 범위로 쓸지 사람이 결정하는 것은 이쪽이에요.
3잠금 파일은 도구로 다시 만들어요. 목록 파일이 정리되면 설치 명령이 새 잠금 파일을 계산해 줘요. 결과 한 장만 남겨요.
4바뀐 줄을 눈으로 훑어요. 내 작업과 상대 작업에서 나온 부품 이름만 보이면 정상이에요. 엉뚱한 이름이 잔뜩 보이면 판이 크게 움직인 거예요.
5연습 무대에서 한 바퀴 눌러 봐요. 연습 무대가 있으면 거기서 결제와 로그인까지요.

팀 규칙	왜 필요한가
이 저장소는 도구 하나만 쓴다	도구를 섞으면 잠금 파일이 두 장 되고, 누가 어떤 명령을 쓰느냐로 결과가 갈려요
잠금 파일은 저장소에 올린다	안 올리면 재현이 불가능해요. 용량 때문에 빼는 것은 부품 폴더 쪽이에요
배포는 잠금 파일을 그대로 따르는 설치만 쓴다	새로 계산하는 설치를 배포에서 쓰면 잠금 파일이 있어도 의미가 옅어져요
잠금 파일 변경은 별도로 검토한다	부품 구성 변경은 코드 변경과 성격이 달라요. 섞여 들어오면 아무도 안 봐요

직접 해보기

내 프로젝트에 명세서가 있는지 확인해 보세요

스튜디오에서 만든 것의 코드를 열고, 파일 이름에 lock 이 들어간 것이 있는지 찾아보세요. 있으면 그것이 오늘의 기준선이에요. 없으면 부품을 받아 쓰는 구조가 아니라서 없는 경우도 있고, 있어야 하는데 빠진 경우도 있어요. 맡긴 곳이 있다면 "잠금 파일 위치와 배포에서 쓰는 설치 명령" 두 가지를 한 번만 물어 두세요.

스튜디오에서 코드 열어 보기

흔한 사고 여섯

증상	실제로 벌어진 일	대응
잠금 파일이 저장소에 안 올라가 있어요	용량이 크다는 이유로 부품 폴더와 함께 제외 목록에 들어갔어요	제외 목록에서 잠금 파일만 빼내요. 창고는 다시 채우면 되지만 명세서는 다시 만들 수 없어요
설치가 안 되니 잠금 파일을 지웠어요	지우면 오류가 사라지는 것처럼 보여요. 기준선을 버린 것이라 다음 배포부터 매번 다른 구성이 깔려요	지운 파일을 되돌려요. 지웠다면 되는 구성을 찾아 다시 못 박아요
재현 설치 명령이 목록과 안 맞는다며 멈춰요	목록 파일만 손으로 고치고 잠금 파일을 다시 만들지 않았어요	손으로 고친 것을 정식 설치 명령으로 다시 반영해 두 장을 맞춰요. 이 멈춤은 고장이 아니라 경고예요
저장소에 잠금 파일이 두 장 있어요	도구를 번갈아 썼어요	쓸 도구를 하나 정하고 나머지 한 장을 지워요. 인수인계 문서에 어느 도구를 쓰는지 한 줄 적어요
내 컴퓨터에서는 되는데 배포 서버에서만 실패해요	운영체제가 달라서 필요한 조각이 다른 경우가 있어요	배포와 같은 환경에서 잠금 파일을 다시 만들어 보고, 그 결과로 배포해요. 원인 좁히기는 같은 오류 다시 만들기 순서로요
봉인 번호가 안 맞는다며 설치가 멈춰요	받아 온 파일이 잠금 파일에 적힌 것과 내용이 다르다는 뜻이에요	겁내지 말고 멈춘 것을 고맙게 봐요. 저장소 주소와 부품 이름 철자를 확인하고, 그래도 계속되면 그 부품 제작자의 공지를 봐요

Q. 잠금 파일만 있으면 부품 사고가 안 나나요?: 아니에요. 잠금 파일은 바뀌지 않게 해 주는 것 이지 부품을 안전하게 만들어 주지는 않아요. 구멍이 발견된 판을 못 박아 두면 그 구멍도 그대로 유지돼요. 그래서 못 박기와 계획적인 갱신은 짝이에요.
Q. 그럼 판을 목록 파일에 정확하게만 적으면 잠금 파일이 필요 없지 않나요?: 그것으로는 절반만 해결돼요. 내가 고른 부품 판은 정해지지만, 그 부품이 기대는 깊은 곳 부품의 판은 여전히 설치할 때 계산돼요. 그 전부를 적어 두는 것이 잠금 파일이에요.
Q. 파일이 몇 만 줄이라 검토가 부담스러워요.: 전부 읽는 파일이 아니에요. 변경 내역에서 부품 이름과 판 번호만 봐요. 대부분의 도구가 무엇이 올라가고 무엇이 내려갔는지 요약해서 보여 줘요.
Q. 이 파일이 손님 정보나 열쇠를 담고 있나요?: 아니에요. 부품 이름과 판 번호, 받아 온 곳 주소가 들어 있어요. 다만 내부 저장소 주소가 적히는 경우가 있어서, 공개 저장소로 옮길 때 그 주소가 밖에 알려도 되는 것인지만 한 번 봐요.
Q. 맡긴 곳에서 "이 파일은 안 올려도 됩니다"라고 해요.: 이유를 물어보세요. 부품을 아예 안 쓰는 구조라면 파일이 없을 수 있어요. 부품을 쓰면서 안 올린다고 하면, 그 순간부터 배포 재현이 운에 맡겨진다는 사실만 짚어 두면 돼요.

하나 더

맡긴 곳이 "부품 하나만 올렸습니다" 라고 했는데, 잠금 파일 변경 내역에 부품 40개 이름이 보여요. 지금 물을 말은?

장면 2 · 인수인계를 받는 개발자가 물었다

“이 프로젝트는 어느 도구를 쓰고, 배포에서 어떤 설치 명령을 쓰나요.”

좋은 질문이고, 답이 문서에 적혀 있어야 하는 질문이에요. 이 두 줄이 없으면 새로 온 사람이 자기 습관대로 설치하고, 그날 잠금 파일이 통째로 갈려요. 넘겨줄 짐을 정리하는 이야기는 내 것을 가지고 나가기에 있어요.

더 깊이 (안 읽어도 괜찮아요)

비유가 어디까지 맞고 어디부터 다른가 · 납품 명세서 비유는 두 가지에서 정확해요. 실제로 들어온 것을 적는다는 점, 그리고 다른 지점을 똑같이 차릴 때 그것을 들고 간다는 점이에요. 다른 점도 하나 있어요. 종이 명세서는 기록일 뿐이지만 잠금 파일은 다음 설치를 실제로 지시해요. 재현 설치 명령은 이 파일을 읽어서 그대로 깔아요. 그래서 이 파일이 틀리면 기록이 틀리는 데서 끝나지 않고 결과물이 틀려요.

판 번호만으로는 부족해서 봉인 번호가 붙었어요 · 같은 판 번호로 파일 내용이 바뀌는 일이 이론상 가능해요. 부품 저장소가 뚫리거나, 제작자가 같은 번호로 다시 올리는 경우예요. 판 번호만 적어 두면 이런 변화를 알 수 없어요. 그래서 잠금 파일은 내려받은 파일 내용을 계산한 값을 함께 적어 둬요. 다음 설치에서 값이 다르면 설치가 멈춰요. 설치가 멈추는 것이 불편해 보이지만, 조용히 다른 코드가 서비스에 들어오는 것보다 훨씬 나은 결과예요.

자동 배포에서 특히 중요한 이유 · 사람이 손으로 배포하면 이상한 낌새를 눈치챌 수 있어요. 자동 배포는 눈치채지 않아요. 코드가 올라오면 정해진 명령을 그대로 돌리고 결과를 라이브에 붙여요. 이 구조에서 설치 명령이 새로 계산하는 쪽이면, 부품이 밤사이 바뀐 날 아침에 아무도 모르게 다른 서비스가 배포돼요. 그래서 자동 배포를 붙이는 날 함께 정해야 하는 것이 잠금 파일과 설치 명령이에요. 흐름은 자동 배포와 빌드에 있어요.

못 박기와 갱신은 반대가 아니에요 · "고정하면 낡는다" 와 "올리면 깨진다" 는 둘 다 맞는 말이라 자주 싸워요. 실제로 두 가지는 순서예요. 평소에는 못 박아 두고 어제와 오늘을 같게 유지해요. 그리고 정한 주기에 의도적으로 갱신해요. 보안 문제가 알려진 것은 그 주기를 기다리지 않고 바로요. 이 리듬을 문서로 적어 두면 부품 관리가 사람의 기억에서 규칙으로 넘어가요. 미룬 만큼 무거워지는 성질은 유지보수에도 나와요.

잠금 파일이 없는데 아무 문제가 없어 보이는 경우 · 부품을 거의 안 쓰는 결과물은 잠금 파일이 없어도 오래 잘 돌아요. 기댈 곳이 없으니 바뀔 것도 없는 상태예요. 다만 이때 기준을 오해하면 안 돼요. "없어도 되는구나" 가 아니라 "기댈 곳이 아직 없구나" 예요. 결제창이나 지도 같은 것을 하나 붙이는 날 성격이 바뀌고, 그날부터는 명세서가 필요해요.

이것만 기억하세요

·목록 파일은 발주서, 잠금 파일은 납품 명세서예요. 재현에 쓰는 것은 명세서예요
·적히는 것은 정확한 판 번호, 받아 온 곳, 봉인 번호, 그리고 딸려 온 부품 전부예요
·손으로 고치지 않아요. 목록 파일을 고치고 설치 명령으로 다시 만들어요
·배포는 잠금 파일을 그대로 따르는 설치만 써요. 새로 계산하면 못 박은 의미가 옅어져요
·충돌은 도구로 다시 만들어 풀고, 갱신은 주기를 정해 의도적으로 해요