Node.js 프로젝트의 Git 협업

Node.js 프로젝트에서 Git 협업을 잘하려면 저장소에 올릴 파일과 올리지 말아야 할 파일을 구분하는 일부터 시작해야 한다. 의존성 디렉터리인 node_modules와 비밀값이 담긴 환경 변수 파일은 제외하고, 잠금 파일(lockfile)은 반드시 커밋해서 모든 팀원이 같은 의존성 트리를 재현할 수 있게 만든다. 그 토대 위에서 기능 브랜치(feature branch)를 나눠 작업하고 풀 리퀘스트(Pull Request) 리뷰를 거쳐 병합하는 흐름이 현대 Node.js 팀의 표준적인 협업 방식이다.

.gitignore로 버전 관리 대상 정하기

Node.js 프로젝트의 저장소에는 소스 코드, 설정 파일, package.json, 잠금 파일처럼 팀원이 공유해야 하는 파일만 올린다. 반대로 node_modules는 package.json과 잠금 파일만 있으면 언제든 다시 설치할 수 있는 파생물이므로 커밋하지 않는다. 수십만 개의 파일이 들어 있어 저장소를 무겁게 만들고, 운영체제마다 네이티브 모듈의 빌드 결과가 달라 오히려 문제를 일으키기 때문이다.

환경 변수 파일인 .env에는 데이터베이스 비밀번호나 API 키 같은 비밀값이 들어가므로 절대 커밋하면 안 된다. 대신 값이 비어 있는 .env.example 파일을 커밋해서 어떤 변수가 필요한지만 공유하는 방식을 많이 쓴다. 빌드 산출물인 dist나 build 디렉터리, 로그 파일, 커버리지 리포트도 모두 제외 대상이다.

# .gitignore 예시
node_modules/
dist/
coverage/
*.log
.env
.env.local

이미 커밋된 파일은 .gitignore에 추가해도 계속 추적되므로, 추적을 끊으려면 다음처럼 인덱스에서만 제거해야 한다.

git rm -r --cached node_modules
git commit -m "chore: node_modules 추적 제거"

잠금 파일은 왜 반드시 커밋하는가

package.json의 의존성 버전은 보통 캐럿(caret) 범위로 적혀 있어서 설치 시점마다 다른 버전이 내려올 수 있다. 예를 들어 ^4.18.0은 4.x 범위의 최신 버전을 허용하므로, 어제 설치한 팀원과 오늘 설치한 팀원의 실제 버전이 달라질 수 있다. package-lock.json 같은 잠금 파일은 직접 의존성뿐 아니라 전이 의존성까지 정확한 버전과 해시를 고정해서 이 문제를 막는다. 잠금 파일을 커밋해야 "내 컴퓨터에서는 되는데요" 문제를 줄이고, 지속적 통합(Continuous Integration, CI) 환경에서도 동일한 빌드를 재현할 수 있다.

CI나 배포 환경에서는 npm install 대신 npm ci를 쓰는 것이 원칙이다. npm ci는 잠금 파일을 절대 수정하지 않고 그대로 설치하며, package.json과 잠금 파일이 어긋나면 실패로 알려 준다.

# 로컬 개발: 의존성 추가 시 잠금 파일이 갱신된다
npm install express

# CI와 배포: 잠금 파일 그대로 설치
npm ci

잠금 파일에서 병합 충돌이 나면 손으로 고치기보다 package.json 충돌만 먼저 해결한 뒤 npm install을 다시 실행해서 잠금 파일을 재생성하는 편이 안전하다. npm은 잠금 파일의 충돌 마커를 감지해서 자동으로 다시 계산해 주기도 한다.

# 최신 메인에서 브랜치 생성
git switch main
git pull origin main
git switch -c feature/<작업-이름>

# 작업 후 원격에 올리고 PR 생성
git add .
git commit -m "feat: 로그인 API 추가"
git push -u origin feature/<작업-이름>