npm audit fix --force 전 확인표와 안전한 수정 순서

npm install이 끝난 뒤 취약점 숫자와 함께 npm audit fix --force가 보이면 당장 복사하고 싶어진다. 하지만 --force는 경고를 지우는 버튼이 아니다. npm audit 공식 문서는 이 옵션이 선언한 의존성 범위를 벗어난 설치와 SemVer 메이저 변경까지 허용할 수 있다고 설명한다.

결론부터 말하면 --force는 첫 명령이 아니라 마지막 후보다. 먼저 어떤 패키지가 왜 설치됐는지 읽고, 되돌릴 Git 체크포인트를 만든 뒤, dry-run으로 변경 범위를 본다. 그다음 호환 범위의 자동 수정과 직접 의존성의 수동 업데이트 중 작은 쪽을 고른다.

npm 취약점 경고와 강제 수정 명령 사이에서 멈춰 점검하는 개발자 터미널 장면

취약점 숫자보다 설치 경로를 먼저 읽는다

npm audit 보고서는 심각도만 보여 주지 않는다. 취약 패키지, 패치된 버전 범위, 그 패키지를 끌고 온 상위 의존성, 설치 경로와 상세 권고 링크를 함께 제공한다. 숫자가 20개라는 사실보다 직접 쓰는 패키지인지, 다른 패키지가 끌고 온 전이 의존성인지가 다음 행동을 더 크게 바꾼다.

일반 보고서에서 패키지 이름을 찾은 뒤 다음 명령으로 설치 이유를 좁힌다.

npm audit
npm explain <취약-패키지-이름>

npm explain은 해당 패키지가 설치된 의존성 사슬을 출력한다. 직접 의존성이면 package.json에서 호환 가능한 패치나 마이너 버전을 검토할 수 있다. 전이 의존성이면 상위 패키지의 업데이트나 공식 권고를 먼저 본다. 설치 트리가 헷갈리면 package-lock을 지우기 전에 npm ci로 원인을 좁히는 순서를 함께 확인한다.

npm audit 보고서에서 의존성 경로를 찾고 수정 경로를 선택하는 가로형 판단 흐름도

수정하기 전에 되돌릴 지점과 예상 변경을 남긴다

현재 작업이 섞인 상태에서 의존성까지 바꾸면 어떤 수정이 화면을 깨뜨렸는지 구분하기 어렵다. 먼저 작업 트리를 확인한다.

git status --short
git diff -- package.json package-lock.json

내 변경이 있다면 커밋하거나 별도 브랜치에 보관한다. 이 단계의 목표는 예쁜 Git 기록이 아니라 의존성 수정 전후를 한 번에 비교할 기준을 남기는 것이다.

그다음 실제 변경 없이 npm이 무엇을 하려는지 본다.

npm audit fix --dry-run --json

출력에서 직접 의존성의 메이저 버전이 바뀌는지, 여러 상위 패키지가 함께 교체되는지, 자동 교정이 불가능하다고 표시되는지 확인한다. 예상하지 않은 메이저 변경이 보이면 여기서 멈춘다. --force를 붙이기 전에 해당 패키지의 릴리스 노트와 마이그레이션 문서를 읽을 차례다.

자동 수정과 수동 업데이트는 변경 범위로 가른다

호환 범위 안에서 끝나면 기본 fix부터 검증한다

dry-run 결과가 선언된 버전 범위 안의 교정만 보여 준다면 기본 명령을 적용해 볼 수 있다.

npm audit fix
git diff -- package.json package-lock.json

npm 문서에 따르면 npm audit fix는 내부적으로 전체 설치 과정을 실행한다. 따라서 명령이 성공했다는 사실만으로 작업이 끝난 것은 아니다. lockfile diff에서 바뀐 패키지와 버전 수를 먼저 읽는다.

메이저 변경이나 직접 의존성 교체가 필요하면 수동으로 좁힌다

--force가 필요하다는 안내는 자동으로 실행해도 된다는 허가가 아니다. 의존성 범위를 바꾸지 않으면 교정할 수 없다는 신호다. 이때는 취약 패키지를 끌고 온 상위 패키지의 호환 버전을 찾고, 한 묶음씩 업데이트한다.

npm install <직접-의존성>@<검토한-버전>
npm explain <취약-패키지-이름>

peer dependency 충돌이 따라오면 강제로 덮지 말고 npm ERESOLVE에서 Found와 peer 버전을 읽는 순서로 돌아간다. 패키지 이름과 메이저 버전을 설명할 수 없으면 --force를 실행하지 않는다.

Git 체크포인트부터 dry-run과 빌드 확인까지 한눈에 보는 npm 의존성 수정 체크리스트

수정 뒤에는 audit 숫자보다 재현과 핵심 화면을 확인한다

깨끗한 설치와 빌드를 재현한다

의존성 변경 뒤에는 새 설치가 재현되는지부터 본다. npm ci는 package.json과 lockfile이 맞지 않으면 수정하지 않고 실패하므로 저장소 상태를 확인하기 좋다.

npm ci
npm run build
npm audit

실패 비용이 큰 화면을 직접 눌러본다

프로젝트에 테스트 명령이 있다면 함께 실행한다. 그다음 로그인, 폼 제출, 파일 업로드, 결제처럼 이 프로젝트에서 실패 비용이 큰 화면을 직접 눌러 본다. 빌드 통과는 회귀 확인의 시작이지 보안 교정의 완전한 증명은 아니다. 남은 권고의 상세 링크와 실제 사용 경로도 다시 확인한다.

최종 확인 상태는 네 가지다.

package.json과 package-lock.json 변경 이유를 설명할 수 있다.
깨끗한 환경에서 설치와 빌드가 재현된다.
핵심 화면이 수정 전과 같이 동작한다.
남은 취약점은 의존성 경로와 대응 계획을 기록했다.

이 네 줄 중 하나라도 답하지 못하면 강제 수정을 반복하지 않는다. 오늘 할 일은 npm audit fix --dry-run --json 결과에서 첫 번째 취약 패키지의 경로 하나를 찾는 것이다.

참고 출처

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.

`npm audit fix --force` 전 확인표: 의존성 경로·dry-run·lockfile diff