패키지 매니저
남이 만든 부품을 받아 오고 무엇을 몇 번 판으로 넣었는지 장부에 적어 두는 도구예요. 무엇이 왜 설치되는지 알아야 배포가 재현되고, 설치가 사고가 되지 않아요.
쉽게 말하면
가게에 들어오는 물건마다 거래처가 달라요. 컵은 컵 공장, 포장지는 인쇄소, 영수증 용지는 문구 도매죠. 사장님이 그때그때 전화를 돌리는 대신 발주 담당자 한 명을 두면, 그 사람이 거래처 목록을 들고 주문·수령·기록을 대신 해요. 패키지 매니저가 그 발주 담당자예요. 무엇을 몇 번 판으로 받았는지 장부에 적고, 같은 장부를 주면 다른 매장에도 똑같이 채워 줘요.
개발에서는 남이 만든 부품 하나를 패키지라고 불러요. 그 패키지를 받아 오고, 버전을 적어 두고, 지울 때 딸려 온 것까지 정리하는 도구가 패키지 매니저예요.
이름은 여러 개예요. 웹 서비스에서 가장 흔한 것이 npm 이고, yarn 과 pnpm 이 같은 일을 다른 방식으로 해요. 파이썬은 pip, PHP 는 Composer 를 써요. 도구 이름이 달라도 사장님이 볼 곳은 같아요.
평소에는 잘 돌아요. 문제는 새 컴퓨터나 배포 서버에 같은 상태를 다시 만들 수 없다는 점이에요. "제 컴퓨터에서는 되는데요"가 여기서 나와요.
사고가 나도 범위가 좁아요. 어제와 오늘의 차이가 파일 두 장에 다 적혀 있어서, 무엇이 달라졌는지 5분 안에 좁혀요.
도구가 실제로 하는 네 가지 일
패키지 매니저는 설치기 하나가 아니에요. 장부와 배송을 같이 맡는 도구 예요. 하는 일을 넷으로 갈라 두면 견적서와 인수인계 문서에 적힌 말이 읽혀요.
| 하는 일 | 실제 동작 | 사장님에게 보이는 모습 |
|---|---|---|
| 찾아오기 | 공개 저장소에 이름으로 요청해서 파일을 받아와요 | 설치할 때 화면에 흐르는 긴 이름 목록이에요 |
| 장부 적기 | 무엇을 어느 버전 범위로 쓰겠다고 목록 파일에 기록해요 | package.json 같은 이름의 파일 한 장이에요. 사람이 읽는 쪽이에요 |
| 딸린 것 챙기기 | 그 부품이 기대는 부품까지 계산해서 함께 내려받아요 | 내가 고른 건 하나인데 목록에는 훨씬 많은 이름이 적혀요 |
| 같은 상태 재현 | 잠금 파일을 그대로 읽어 다른 컴퓨터에도 같은 판을 깔아요 | 외주 개발자 컴퓨터와 배포 서버가 같아지는 이유예요 |
하나를 고르면 여럿이 따라와요
부품 제작자도 남의 부품을 써요. 그래서 내가 하나를 설치하면 그것이 기대는 부품, 또 그것이 기대는 부품까지 함께 들어와요. 목록이 길어 보이는 건 도구가 일을 잘못한 게 아니라 원래 그런 구조예요. 부품을 자산이자 위험으로 세는 이야기는 남이 만든 부품에 있어요.
장부 두 장과 창고 한 칸
부품 관리에서 사장님이 알아야 할 물건은 딱 세 개예요. 목록 파일, 잠금 파일, 그리고 부품이 실제로 쌓이는 폴더요. 셋의 성격이 완전히 달라요.
| 이름 | 무엇인가 | 저장소에 올리나 |
|---|---|---|
| 목록 파일 | 내가 쓰겠다고 고른 부품과 허용 버전 범위를 적은 장부예요. 사람이 읽고 고치는 쪽이에요 | 올려요. 이 파일이 없으면 무엇을 쓰는지 아무도 몰라요 |
| 잠금 파일 | 실제로 깔린 판이 몇 번인지 부품마다 한 줄씩 못 박아 둔 기록이에요. 기계가 읽는 쪽이에요 | 올려요. 이걸 빠뜨리는 것이 재현 안 되는 배포의 가장 흔한 원인이에요 |
| 부품 폴더 | 받아 온 파일이 쌓이는 창고예요. 파일 수와 용량이 아주 커요 | 올리지 않아요. 지워도 장부 두 장만 있으면 다시 채워져요 |
여기서 나오는 실수가 하나 있어요. 용량이 크다는 이유로 잠금 파일까지 함께 빼 버리는 거예요. 창고는 다시 채우면 되지만, 못 박아 둔 판 번호를 잃으면 어제와 같은 상태를 두 번 다시 만들 수 없어요.
확인해 보세요
외주 개발자가 "용량이 커서 부품 관련 파일은 저장소에서 다 뺐습니다"라고 했어요. 지금 확인할 것은?
버전 앞에 붙은 기호 한 글자
목록 파일을 열면 버전 앞에 기호가 붙어 있어요. 이 한 글자가 다음에 설치할 때 새 판을 받을지 말지 를 정해요. 어제 되던 배포가 오늘 깨지는 사고의 절반이 이 글자에서 나와요.
| 표기 | 허용하는 범위 | 성격 |
|---|---|---|
| ^1.4.2 | 1.4.2 이상이면서 2.0.0 전까지 받아요 | 가장 흔한 기본값이에요. 편하지만 내가 안 고쳐도 부품이 바뀌어요 |
| ~1.4.2 | 1.4.2 이상이면서 1.5.0 전까지 받아요 | 고친 판만 받는 보수적인 선택이에요 |
| 1.4.2 | 정확히 이 판만 받아요 | 결제·인증처럼 흔들리면 안 되는 자리에 써요 |
| 앞자리가 0 인 부품 | ^0.4.2 는 0.5.0 전까지만 받아요 | 아직 규격이 굳지 않았다는 뜻이라 기호가 있어도 조심해요 |
기호가 있어도 잠금 파일이 이겨요
허용 범위는 "새로 계산할 때 어디까지 받아도 되는가"일 뿐이에요. 잠금 파일이 있으면 재현 설치는 거기 적힌 판을 그대로 깔아요. 그래서 기호를 느슨하게 두더라도 잠금 파일만 저장소에 있으면 어제와 오늘이 같아요. 앞자리가 올라가는 사건 자체는 버전 번호 규칙에서 다뤄요.
명령 한 줄 차이로 배포가 갈려요
설치 명령은 두 종류예요. 하나는 장부를 새로 계산하는 설치 고, 하나는 잠금 파일을 그대로 따르는 설치 예요. 배포 서버에서 어느 쪽을 쓰는지가 재현 가능한 서비스와 아닌 서비스를 갈라요.
| 언제 쓰나 | 무엇을 하나 | 결과 |
|---|---|---|
| 부품을 새로 넣거나 올릴 때 | 허용 범위 안에서 판을 다시 계산하고, 잠금 파일도 함께 고쳐 써요 | 장부가 갱신돼요. 이 변경은 사람이 검토하고 저장소에 올려야 해요 |
| 배포 서버가 깔 때 | 잠금 파일에 적힌 판만 그대로 깔아요. 장부와 어긋나면 아예 멈춰요 | 어제와 같은 상태가 보장돼요. 조용히 다른 판이 들어오지 않아요 |
설치는 남의 코드를 내 컴퓨터에서 실행하는 일이에요
이 문장이 이 문서에서 가장 중요해요. 부품 설치는 파일을 내려받는 것으로 끝나지 않아요. 설치 직후 자동으로 실행되도록 짜여 있는 부분이 있어서, 이름을 한 번 잘못 적으면 내 컴퓨터에서 남의 코드가 돌아요.
- 1이름 철자를 눈으로 확인해요. 유명한 부품과 한 글자만 다른 이름을 만들어 두고 오타를 기다리는 수법이 실제로 있어요. 검색 결과 첫 줄이 아니라 공식 문서에 적힌 링크를 따라가요.
- 2받는 곳이 공식 저장소인지 봐요. 낯선 주소에서 파일로 받아 넣는 방식은 장부에도 안 남고 조회도 안 돼요.
- 3최근 수정과 쓰는 양을 봐요. 몇 년째 조용한 부품은 구멍이 나와도 고쳐 줄 사람이 없어요. 고르는 기준 다섯 칸은 남이 만든 부품에 정리돼 있어요.
- 4알려진 구멍 조회를 주기로 만들어요. 패키지 매니저에는 목록을 훑어 알려진 취약점을 보고하는 기능이 있어요. 분기에 한 번은 돌려요.
- 5설치 시 자동 실행을 막는 옵션을 알아 둬요. 낯선 부품을 시험할 때만 쓰면 돼요. 항상 끄면 정상 부품이 안 깔릴 수 있어요.
- 6잠금 파일 변경을 검토 대상에 올려요. 이 파일이 바뀌었다면 부품 구성이 바뀐 거예요. 코드 검토에서 그냥 넘기지 않아요.
- Q. 설치할 때 경고가 여러 줄 뜨는데 그냥 넘겨도 되나요?
- 경고와 실패는 달라요. 실패는 멈추고, 경고는 진행돼요. 다만 취약점 보고에서 "높음"으로 나온 항목은 고친 판이 있는지 확인할 값이 있어요. 이때도 한꺼번에 다 올리지 말고 그 부품만 올려요.
- Q. 부품 폴더를 지워도 되나요?
- 돼요. 장부 두 장이 있으면 다시 채워져요. 오히려 이상한 상태가 계속될 때 폴더를 비우고 다시 깔아 보는 것이 가장 빠른 확인법이에요.
- Q. 도구를 npm 에서 다른 것으로 바꾸면 좋아지나요?
- 속도와 용량에서 차이가 나요. 다만 도구를 바꾸면 잠금 파일 종류가 달라져서 팀 전체가 같은 것을 써야 해요. 지금 잘 돌아가고 있다면 바꿀 이유부터 적어 보세요.
- Q. 부품을 지웠는데 폴더 용량이 그대로예요.
- 지운 부품에만 딸려 있던 것들이 남아 있는 경우예요. 폴더를 비우고 다시 깔면 정리돼요. 목록 파일에서 이름이 사라졌는지도 함께 확인하세요.
바이브캠퍼스에서 만든 것은
스튜디오 결과물은 한 파일 구조를 기본으로 해요. 그래서 부품 목록 파일이 아예 없는 경우가 많고, 처음에는 패키지 매니저를 쓸 일이 없어요. 관리할 거래처가 0곳이라는 뜻이라 이건 약점이 아니라 강점이에요.
도구가 등장하는 시점은 정해져 있어요. 코드를 내보내서 개발자에게 넘기거나, 기능이 커져서 여러 파일로 나눌 때예요. 그날부터는 장부 두 장이 내 자산 목록이 돼요.
직접 해보기
내 결과물에 부품 장부가 있는지 확인해 보세요
스튜디오에서 만든 결과물의 코드를 열고 package.json 이라는 이름의 파일 이 있는지 보세요. 없으면 한 파일 구조라는 뜻이고, 관리할 부품이 없다는 좋은 신호예요. 있으면 그 안 dependencies 칸에 적힌 이름 개수가 내가 관리할 거래처 수예요. 오늘 아무것도 고치지 않아도 값이 있는 확인이에요.
스튜디오에서 코드 열어 보기하나 더
3주 동안 코드를 한 줄도 안 고쳤는데 오늘 배포가 실패했어요. 패키지 매니저 쪽에서 먼저 확인할 것은?
더 깊이 (안 읽어도 괜찮아요)
왜 잠금 파일이 저장소에 있어야 하나 · 허용 범위만 적혀 있으면 설치하는 날짜에 따라 결과가 달라져요. 같은 코드가 어제는 1.4.2 로, 오늘은 1.9.0 으로 깔릴 수 있어요. 잠금 파일은 그 계산 결과를 한 번 못 박아 저장해 둔 것이에요. 그래서 이 파일이 저장소에 있으면 내 컴퓨터·외주 컴퓨터·배포 서버가 같은 부품 구성을 갖게 돼요. 판을 못 박는 원리와 갱신 요령은 잠금 파일에서 더 다뤄요.
만들 때만 쓰는 부품과 손님에게 나가는 부품 · 목록 파일은 부품을 두 칸으로 갈라 적어요. 하나는 실제 서비스가 돌아갈 때 필요한 것, 하나는 만드는 동안만 필요한 것(점검 도구·변환 도구 같은 것)이에요. 이 구분이 중요한 이유는 둘이에요. 손님에게 나가는 쪽에 무거운 것이 섞이면 화면이 느려져요. 그리고 만들 때만 쓰는 쪽은 취약점 보고가 떠도 위험의 성격이 달라요. 견적을 받을 때 "어느 칸에 넣는지"를 물으면 상대의 실력이 보여요.
"부품을 전부 최신으로"가 위험한 이유 · 여러 개를 한꺼번에 올리면 문제가 났을 때 범인을 못 가려요. 순서는 이래요. 취약점 보고가 있는 것만 먼저, 하나씩, 올린 뒤 결제·로그인처럼 돈과 손님이 걸린 화면을 실제로 눌러 확인, 그리고 돌아갈 곳을 정해 두고요. 이 확인 한 바퀴가 고쳤더니 딴 게 깨짐을 잡는 자리예요.
도구를 섞어 쓰면 생기는 일 · 한 프로젝트에서 npm 과 yarn 을 번갈아 쓰면 잠금 파일이 두 장 생겨요. 두 장이 서로 다른 판을 가리키면 누가 어떤 명령을 쓰느냐에 따라 결과가 달라져요. 그래서 인수인계 문서에 "이 프로젝트는 어느 도구를 쓴다"를 한 줄로 못 박아 둬요. 이런 약속을 적어 두는 자리가 README와 인수인계 문서예요.
이것만 기억하세요
- ·패키지 매니저는 발주 담당자예요. 받아 오고, 적어 두고, 같은 상태를 다시 만들어 줘요
- ·저장소에 남아야 하는 건 목록 파일과 잠금 파일이에요. 부품 폴더는 빼도 돼요
- ·버전 앞의 기호는 새 판을 받을 범위예요. 흔들리면 안 되는 자리는 정확한 판으로 못 박아요
- ·배포 서버는 잠금 파일을 그대로 따르는 설치를 써야 어제와 오늘이 같아요
- ·설치는 남의 코드를 내 컴퓨터에서 실행하는 일이에요. 이름 철자와 취약점 조회를 습관으로 만들어요