GitHub Actions npm ci 실패 해결: lockfile과 Node 버전 확인

증상

GitHub Actions에서 다음 단계가 실패합니다.

- run: npm ci

로컬에서는 npm install 후 프로젝트가 실행될 수 있지만 CI에서는 설치 단계에서 멈춥니다.

환경

GitHub Actions
Node.js
npm
package.json
package-lock.json

목차

1. npm install과 npm ci 차이
2. 최소 재현
3. 원인 1: lockfile 불일치
4. 원인 2: Node/npm 버전 차이
5. 원인 3: package manager 혼용
6. install 옵션 차이도 확인합니다
7. 수정 전
8. 수정 후
9. 실습 프로젝트 전체 코드
10. 추가 점검
11. 학습 완료 체크리스트
12. TaskFlow 프로젝트 적용
13. 실습 경로·결과·복구
14. 다음 학습
15. 공식 문서
16. 단독 실습과 결과 확인

npm install과 npm ci 차이

npm install은 package.json을 기준으로 의존성을 설치하고 필요한 경우 package-lock.json을 갱신할 수 있습니다.

npm ci는 다른 목적을 가집니다.

npm install
→ 개발 중 의존성 추가·갱신 가능

npm ci
→ lockfile을 그대로 재현하는 clean install

npm ci의 핵심 특성은 다음과 같습니다.

• package-lock.json이 필요합니다.
• package.json과 lockfile이 맞지 않으면 실패합니다.
• 기존 node_modules를 제거한 뒤 설치합니다.
• package.json이나 package-lock.json을 수정하지 않습니다.

CI에서 이 엄격함은 단점이 아니라 재현성을 높이기 위한 동작입니다.

최소 재현

예를 들어 package.json에는 새 패키지가 추가되었지만 package-lock.json은 이전 상태라고 가정합니다.

{
  "dependencies": {
    "axios": "^1.0.0",
    "zod": "^4.0.0"
  }
}

그런데 lockfile이 axios만 알고 있다면 npm ci는 두 파일의 상태가 맞지 않는다고 판단할 수 있습니다.

흔한 발생 흐름은 다음과 같습니다.

package.json 수동 수정
↓
package-lock.json 갱신 안 함
↓
package.json만 commit
↓
CI에서 npm ci
↓
실패

원인 1: lockfile 불일치

가장 먼저 로컬에서 clean install을 재현합니다.

npm ci

로컬에서도 같은 오류가 발생한다면 CI 설정 이전에 저장소의 의존성 상태를 수정해야 합니다.

정상적인 수정 흐름은 다음과 같습니다.

npm install
npm ci
npm run build
git status

npm install로 lockfile을 현재 package.json과 맞춘 뒤 package-lock.json 변경을 확인합니다.

git diff -- package.json package-lock.json

의도한 변경이면 package.json과 package-lock.json을 함께 commit합니다.

lockfile을 이유 없이 삭제하고 CI가 알아서 새로 만들게 하는 방식은 npm ci의 목적과 맞지 않습니다.

원인 2: Node/npm 버전 차이

로컬과 CI의 Node 버전이 크게 다르면 의존성 설치나 build 결과가 달라질 수 있습니다.

GitHub Actions에서는 setup-node로 사용할 Node 버전을 명시할 수 있습니다.

- name: Setup Node.js
  uses: actions/setup-node@v7
  with:
    node-version: "24.x"
    cache: "npm"

프로젝트가 요구하는 Node 버전이 따로 있다면 package.json의 engines나 .nvmrc 같은 기준과 workflow를 맞춥니다.

{
  "engines": {
    "node": "24.x"
  }
}

중요한 것은 예시의 24.x를 모든 프로젝트에 강제하는 것이 아니라 프로젝트 기준과 CI 기준을 일치시키는 것입니다.

원인 3: package manager 혼용

저장소에 다음 파일이 동시에 존재하면 어떤 package manager가 기준인지 불분명해질 수 있습니다.

package-lock.json
pnpm-lock.yaml
yarn.lock

의도적인 마이그레이션 중이 아니라면 프로젝트 기준 package manager와 lockfile을 하나로 정리합니다.

npm 프로젝트라면 다음처럼 운영할 수 있습니다.

package manager: npm
lockfile: package-lock.json
CI install: npm ci

pnpm이나 Yarn을 사용한다면 해당 package manager의 고정 설치 방식과 lockfile을 사용해야 합니다.

install 옵션 차이도 확인합니다

npm 공식 문서는 lockfile을 만들 때 dependency tree에 영향을 주는 특정 옵션을 사용했다면 npm ci에서도 같은 설정이 필요할 수 있다고 설명합니다.

예를 들어 로컬에서 항상 --legacy-peer-deps를 사용해 lockfile을 만들었다면 CI만 기본 설정으로 npm ci를 실행할 때 차이가 생길 수 있습니다.

이 경우 임시로 CI 명령 뒤에 옵션을 붙이는 것보다 왜 해당 설정이 필요한지 확인하고 프로젝트 .npmrc로 명시할지를 판단합니다.

수정 전

steps:
  - uses: actions/checkout@v7
  - run: npm ci
  - run: npm run build

Node 버전이 명시되지 않았고 저장소의 lockfile이 현재 package.json과 다르다면 재현성이 떨어집니다.

수정 후

name: CI

on:
  push:
    branches:
      - main
  pull_request:

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24.x"
          cache: "npm"

      - name: Install dependencies
        run: npm ci

      - name: Build
        run: npm run build

actions/checkout과 setup-node의 major version은 GitHub 공식 문서의 현재 예시와 프로젝트 정책을 확인해 사용합니다.

추가 점검

npm ci는 통과하지만 build가 실패합니다

설치 문제는 해결된 것입니다. 다음 단계의 TypeScript, lint, 환경변수, framework build 로그를 확인합니다.

cache를 지우면 해결될 것 같아서 먼저 삭제합니다

cache는 원인을 가릴 수 있지만 첫 번째 해결책으로 사용하지 않습니다. lockfile과 버전 기준을 먼저 확인합니다.

package-lock.json을 .gitignore에 넣습니다

애플리케이션 저장소에서 npm ci를 사용할 계획이라면 lockfile을 commit하는 것이 재현성에 중요합니다.

학습 완료 체크리스트

• npm install과 npm ci 차이를 설명할 수 있습니다.
• package.json과 package-lock.json 불일치를 확인할 수 있습니다.
• CI에서 Node 버전을 명시할 수 있습니다.
• package manager 혼용 여부를 확인할 수 있습니다.
• install 단계와 build 단계를 구분해서 진단할 수 있습니다.

name: CI


on:
  push:
    branches:
      - main
  pull_request:


jobs:
  build:
    runs-on: ubuntu-latest


    steps:
      - name: Checkout
        uses: actions/checkout@v7


      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24.x"
          cache: "npm"


      - name: Install dependencies
        run: npm ci


      - name: Build
        run: npm run build

# 기존 앱에서 실제 사용하는 변수만 설정하세요. 값은 개발/운영 플랫폼에서 별도 관리합니다.
NEXT_PUBLIC_API_URL=
API_SECRET=

name: CI


on:
  push:
    branches:
      - main
  pull_request:


jobs:
  build:
    runs-on: ubuntu-latest


    steps:
      - name: Checkout
        uses: actions/checkout@v7


      - name: Setup Node.js
        uses: actions/setup-node@v7
        with:
          node-version: "24.x"
          cache: "npm"


      - name: Install dependencies
        run: npm ci


      - name: Build
        run: npm run build

24

# TaskFlow Deployment Plan


## Build
- package manager: npm
- install: npm ci
- build: npm run build


## Primary deployment
- platform: Vercel
- environment: Production


## Alternative deployment
- Firebase Hosting: static output일 때 검토
- Firebase App Hosting: server runtime이 필요할 때 검토


## Verification
- Production URL 응답
- 주요 화면 확인
- 환경변수 확인
- 주요 route 확인
- 현재 commit 확인
- rollback 가능 여부 확인

## Runtime decision


- static-only: no
- server runtime required: yes
- reasons:
  - Route Handler
  - server-side environment variables


## Primary
Vercel Production


## Firebase alternative
App Hosting 우선 검토


## Static variant
정적 결과물로 분리할 경우 Firebase Hosting 검토

## Production deployment


- deployment URL: 운영 문서에서 관리
- commit SHA: 배포마다 기록
- deployment status: 확인
- build log: 확인
- smoke test: 확인

## Domain


- canonical domain: 운영 문서에서 관리
- www policy: canonical로 redirect
- HTTPS: 확인
- DNS status: 확인
- auth callback / allowed origin: 확인

# Server Access Runbook


## Connection
- host: 저장하지 않음
- user: 환경별 문서에서 별도 관리
- authentication: SSH key 우선
- private key: 저장소에 포함 금지


## Before upload
1. 대상 서버 확인
2. 현재 경로 확인
3. 배포 대상 경로 확인
4. 기존 파일 상태 확인


## After upload
1. 파일 존재 확인
2. owner / permission 확인
3. 서비스가 실제 경로를 읽는지 확인
4. HTTP 결과 확인


## Never commit
- private key
- password
- access token
- production secret

# 배포·서버 06 — deploy-step-06-ci-install

이 ZIP은 배포 준비·운영 문서와 해당 회차 설정/코드 조각을 누적한 적용 자료입니다. 실행 앱 전체는 포함하지 않습니다. 기존 deploy-step-00-build-ready 프로젝트에 해당 파일을 검토하여 적용하세요. 이 ZIP 루트에서 npm ci/build를 실행하는 구조가 아닙니다.

.env.example은 값이 빈 설정 안내입니다. 독자의 앱에서 사용하는 변수만 .env.local 또는 플랫폼의 해당 환경에 설정하세요. URL·계정·비밀키를 ZIP에 넣지 않습니다.

CI workflow는 이미 package.json/package-lock.json과 build 스크립트가 있는 기존 npm 프로젝트 루트에 적용합니다. actions/checkout@v7, actions/setup-node@v7, Node 24.x를 사용합니다. GitHub 원격 실행은 검증하지 않았습니다.

이 자료에는 실제 배포·DNS 변경·SSH 접속·메일/알림·롤백 결과가 없습니다. 운영 작업은 독자가 본인 환경과 권한을 확인한 후 수행해야 합니다. 문서의 확인 항목은 수행할 체크리스트이며 이미 통과했다는 기록이 아닙니다.

deploy-step-05-domain-https

.github/
└─ workflows/
   └─ ci.yml

npm ci
npm run build

deploy-step-06-ci-install

다음 학습

다음 글에서는 CI 설치는 통과하지만 Vercel build 단계에서 실패하는 경우를 build log, 환경변수, 타입 오류, Node 설정으로 나눠 확인합니다.

다음 글: Vercel Next.js 배포 실패 해결 체크리스트

다음 회차 확인 과제: 07회차에서는 설치는 통과하지만 Vercel build가 실패하는 경우 첫 오류 행과 로컬 재현 결과를 대조합니다.

공식 문서

공식 문서 확인 기준: 2026-09-21

• https://docs.npmjs.com/cli/commands/npm-ci/
• https://docs.npmjs.com/files/package-lock.json
• https://docs.github.com/en/actions/tutorials/build-and-test-code/nodejs