npm install 후 앱이 켜지지 않을 때 현재 폴더, Node 버전, package.json, 설치 로그, 환경변수, 실행 명령을 확인하는 순서를 설명합니다.
npm install 오류는 재설치를 반복하기 전에 현재 폴더, 버전, 첫 오류 메시지를 고정해서 비교해야 원인을 찾기 쉽습니다.
연재 안내: 27편 전체 순서와 현재 공개된 글은 비개발자 바이브코딩 로드맵에서 확인할 수 있습니다.
설치 전에 비밀값부터 분리하려면 API 키 환경변수 사용법을 확인하세요.
한 줄 답변
npm install 후 앱이 안 켜지면 코드를 바로 고치지 말고 현재 폴더, Node·npm 버전, package.json, 첫 오류 메시지, 환경변수, 실행 명령을 순서대로 확인해야 합니다. 무작정 재설치하면 원인이 가려질 수 있습니다.
npm install은 무엇을 하는가
npm install은 현재 폴더의 package.json을 읽고 프로젝트에 필요한 패키지를 node_modules에 설치합니다. package-lock.json이 있다면 가능한 범위에서 기록된 버전 조합을 재현합니다.
따라서 명령이 성공했다고 앱까지 자동으로 실행되는 것은 아닙니다. 설치가 끝난 뒤에는 package.json의 scripts에 적힌 npm run dev, npm start 같은 실행 명령을 별도로 사용합니다.
1. 지금 어느 폴더인지 확인한다
가장 흔한 원인은 프로젝트가 아닌 상위 폴더에서 명령을 실행한 경우입니다. 터미널의 현재 경로와 파일 목록을 확인하고 그 위치에 package.json이 있는지 봅니다.
여러 프로젝트를 열어둔 상태라면 AI에게 보여준 코드 폴더와 터미널이 가리키는 폴더가 같은지도 확인하세요. package.json을 찾을 수 없다는 오류는 설치 문제보다 현재 위치 문제일 수 있습니다.
2. Node와 npm 버전을 확인한다
터미널에서 다음 명령으로 설치 여부와 버전을 확인합니다.
node --version
npm --version프로젝트의 README, package.json의 engines, .nvmrc에 권장 Node 버전이 적혀 있다면 맞춰야 합니다. 너무 오래되거나 너무 새로운 버전에서 패키지가 호환되지 않을 수 있습니다. 버전을 바꾸기 전에는 현재 값을 기록하세요.
3. 첫 오류부터 읽는다
빨간 로그가 길어도 마지막 줄만 보지 마세요. 뒤의 오류는 첫 실패 때문에 연속으로 생긴 결과일 수 있습니다. 처음 등장한 ERR!, Cannot find, permission, version 근처를 확인하고 전체 로그를 파일로 보관합니다.
필요하면 npm 공식 문서가 안내하는 verbose 옵션으로 상세 정보를 확인할 수 있습니다.
npm install --verboseAPI 키, 토큰, 사용자 경로가 포함될 수 있으므로 로그를 AI나 공개 게시판에 붙이기 전에 민감정보를 가립니다.
4. package.json과 잠금 파일을 확인한다
package.json의 문법이 깨졌거나 필요한 패키지가 dependencies에 없으면 설치가 실패합니다. 쉼표 하나가 빠져도 JSON 파싱 오류가 납니다. package-lock.json은 설치 버전 조합을 고정하는 기록이므로 이유 없이 삭제하지 마세요.
AI가 오래된 예제의 패키지 버전을 제안했거나 서로 다른 패키지가 호환되지 않는 버전을 요구할 수도 있습니다. 오류 로그의 peer dependency(함께 설치돼야 하는 패키지 조건)와 요구 버전을 비교하고 공식 패키지 문서에서 호환 범위를 확인합니다.
5. 설치와 실행 오류를 구분한다
npm install은 성공했지만 npm run dev가 실패한다면 설치보다 실행 설정을 봐야 합니다. scripts에 해당 명령이 있는지, 필요한 .env 값이 있는지, 사용하려는 포트가 이미 점유됐는지 확인합니다.
화면은 열리지만 API 요청만 실패한다면 Node 설치 문제가 아니라 서버 주소, 환경변수, CORS(서로 다른 주소 사이의 요청 허용 규칙), 인증 문제일 수 있습니다. 단계가 다른 문제를 한꺼번에 해결하려 하지 마세요.
6. 무작정 삭제하기 전에 정상 상태를 남긴다
인터넷에는 node_modules와 잠금 파일을 모두 삭제하고 다시 설치하라는 답이 많습니다. 때로는 도움이 되지만 버전 조합을 바꾸고 재현 단서를 없앨 수 있습니다. 먼저 Git 상태, Node 버전, 오류 로그, 잠금 파일을 기록하세요.
그다음 프로젝트 공식 설치 절차가 깨끗한 재설치를 요구할 때만 범위를 확인해 실행합니다. 권한 오류를 피하려고 관리자 권한으로 모든 명령을 실행하거나 SSL 검사를 끄는 식의 우회는 보안 위험을 만들 수 있습니다.
AI에게 전달할 진단 정보
운영체제,
node --version,npm --version, 현재 폴더의package.jsonscripts, 실행한 정확한 명령, 첫 오류부터의 로그를 줄 테니 원인을 설치·버전·권한·환경변수·실행 단계로 나눠줘. 파일 삭제나 전역 설치를 제안하기 전에 왜 필요한지와 되돌리는 방법을 설명해줘.
npm의 현재 오류 분류와 설치 동작은 npm Common errors와 로컬 패키지 설치 문서에서 확인할 수 있습니다.
해결 뒤 재현 정보를 남긴다
오류가 해결되면 사용한 Node·npm 버전, 실행 명령, 필요한 환경변수 이름, 설치에 필요한 추가 조건을 README에 적습니다. 새 컴퓨터나 깨끗한 폴더에서 같은 절차로 다시 실행할 수 있는지 확인하면 “내 컴퓨터에서만 되는” 상태를 줄일 수 있습니다.
임시 우회 명령을 사용했다면 이유와 제거 시점도 기록하세요. 다음 설치에서 같은 오류가 나오지 않는 것이 진짜 해결입니다.
npm install 오류 최종 점검
npm install 오류를 해결할 때는 명령을 실행한 경로, Node·npm 버전, package.json과 잠금 파일 존재 여부, 첫 오류 문장을 한 화면에 모으세요. npm install 오류 뒤에 나온 수십 줄 중 마지막 문장만 복사하면 실제 원인인 권한, 버전 충돌, 패키지 누락을 놓칠 수 있습니다.
AI에게 질문할 때는 운영체제, 방금 실행한 정확한 명령, 이전에는 되었는지, 다른 프로젝트는 실행되는지도 함께 전달하세요. 삭제나 재설치를 제안받았다면 무엇을 지우는지와 되돌릴 방법을 먼저 확인하고 프로젝트 원본과 환경변수 파일을 백업합니다.
설치가 성공한 뒤에는 package.json의 scripts에서 정확한 실행 명령을 확인하고 브라우저 주소와 터미널 로그를 함께 봅니다. 앱이 켜져도 API 요청이나 환경변수 로딩이 실패할 수 있으므로 핵심 기능 한 가지까지 실행해야 해결이 끝난 것입니다.
공식 npm 문서의 일반 오류 항목과 프로젝트가 요구하는 Node 버전을 비교하되, 인터넷에서 찾은 명령을 그대로 실행하지 마세요. 특히 전역 설치, 캐시 삭제, 관리자 권한 실행은 현재 증거와 관련이 있을 때만 하나씩 시도하고 결과를 기록합니다.
설치와 실행 문제가 해결됐는데 기능을 붙일수록 코드가 흔들린다면 다음 글인 AI 코드 꼬임: 기능이 깨지는 이유에서 생성 속도, 역할 혼재, 중복 코드의 위험 신호를 확인하세요.
바이브코딩 전체 순서 보기
바이브코딩 뜻, 하는법, 도구 선택, API 연결, 데이터베이스, 배포 흐름은 바이브코딩 가이드에서 이어서 볼 수 있습니다.
