# 설치

> **이 챕터를 마치면** Cursor, Node.js, pnpm을 설치하고 바이브코딩을 시작할 수 있어요.

개발 환경을 구성해 보세요. Cursor와 Node.js를 설치하면 바이브코딩을 시작할 수 있어요.

> **소요 시간:** 약 10~15분
> **지원 OS:** macOS, Windows, Linux

---

## macOS 전용: Homebrew로 한 번에 설치

맥 사용자라면 **Homebrew**로 Node.js, pnpm, Git을 터미널에서 한 번에 설치할 수 있어요. 나중에 Claude Code, Gemini CLI, Google Workspace CLI 같은 도구도 `brew`로 관리하기 편해요.

### Homebrew 설치 (아직 없다면)

<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://brew.sh" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/homebrew-install.png" alt="Homebrew 공식 사이트 — brew.sh" className="w-full h-auto" />
  </a>
</div>

터미널(Terminal 또는 iTerm)을 열고 아래 한 줄을 붙여 넣고 실행해요.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

설치가 끝나면 터미널에 나오는 **"Next steps"** 안내대로 `brew`를 PATH에 넣어줘요. (예: `echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile` 후 터미널 재시작)

설치 확인:

```bash
brew --version
# Homebrew 4.x.x
```

### Homebrew로 Node.js · pnpm · Git 설치

아래 명령어만 실행하면 돼요.

```bash
# Node.js (LTS)
brew install node@22

# PATH에 node 22 넣기 (Apple Silicon 기준)
echo 'export PATH="/opt/homebrew/opt/node@22/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# pnpm (전역)
npm install -g pnpm

# Git (이미 Xcode CLI에 있을 수 있음)
brew install git
```

확인:

```bash
node --version   # v22.x.x
pnpm --version  # 9.x 이상
git --version   # 2.x.x
```

### Homebrew로 그 밖의 도구 설치 (선택)

이 커리큘럼에서 나중에 쓰는 CLI 도구들도 `brew`로 설치할 수 있어요.

| 도구 | 설치 명령 | 비고 |
|------|-----------|------|
| **Claude Code** | `brew install anthropic-ai/tap/claude-code` | 공식 tap |
| **Gemini CLI** | `npm install -g @google/gemini-cli` | npm 권장 |
| **Google Workspace CLI (gws)** | `npm install -g @googleworkspace/cli` | npm 권장 |
| **pnpm** | `brew install pnpm` | 또는 `npm i -g pnpm` |

> **참고:** Cursor는 GUI 앱이라 [cursor.com/downloads](https://www.cursor.com/downloads)에서 다운로드하는 방식을 권장해요. `brew install --cask cursor` 로도 설치 가능해요.

---

## 1. [Cursor](https://www.cursor.com/downloads)

<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://www.cursor.com/downloads" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/cursor-download.png" alt="Cursor 공식 다운로드 — Download for your OS" className="w-full h-auto" />
  </a>
</div>

AI 코딩 에디터 Cursor를 설치해 보세요.

`Download for [현재 컴퓨터의 운영체제]` 버튼을 눌러서 다운받아 보세요. ([다운로드 페이지](https://www.cursor.com/downloads))

설치 후 처음 실행 시:
1. [Continue with GitHub](https://www.cursor.com/downloads) 로그인
2. 에디터 테마 선택 (Dark 권장)
3. 키바인딩 설정 (VS Code 사용자는 VS Code 선택)

> **2026 기준 최신 버전:** Cursor 0.47+ | AI 모델: Claude 3.7 Sonnet, GPT-4o, Gemini 2.0 Flash

### Cursor 첫 설정

설치 후 아래 설정을 확인하세요:
- **설정 열기:** `Cmd+,` (macOS) / `Ctrl+,` (Windows)
- **AI 모델:** `claude-3-7-sonnet` 권장 (코드 이해력 최고)
- **자동완성:** Tab 키로 수락, Esc 키로 거절

---

## 2. [Node.js](https://nodejs.org/ko) (LTS)

<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://nodejs.org/ko" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/nodejs-download.png" alt="Node.js 공식 사이트 — Run JavaScript Everywhere, Get Node.js 다운로드" className="w-full h-auto" />
  </a>
</div>

JavaScript 런타임 환경입니다. Next.js 앱 실행과 패키지 관리에 필요합니다.

[Node.js 다운로드 (LTS)](https://nodejs.org/ko) 버튼을 눌러서 다운로드 받아주세요.

> **2026 기준 LTS:** Node.js 22.x (추천) — 짝수 버전이 LTS입니다.

설치 확인 (터미널에서):

```bash
node --version
# v22.x.x 이상이면 정상

npm --version
# 10.x.x 이상이면 정상
```

---

## 3. pnpm 설치

빠르고 효율적인 패키지 매니저입니다. npm보다 설치 속도가 2~3배 빠르고 디스크 공간을 절약합니다.

터미널을 열고 아래 명령어를 실행하세요:

```bash
npm install -g pnpm
```

설치 확인:

```bash
pnpm --version
# 9.x.x 이상이면 정상
```

> **pnpm vs npm:**
> - `npm install` → `pnpm install`
> - `npm run dev` → `pnpm dev`
> - `npm install [패키지]` → `pnpm add [패키지]`

---

## 4. Git 확인

<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://git-scm.com/" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/git-download.png" alt="Git 공식 사이트 — git-scm.com 다운로드" className="w-full h-auto" />
  </a>
</div>

GitHub 연동에 필요한 Git이 설치되어 있는지 확인합니다.

```bash
git --version
# git version 2.x.x 이상이면 정상
```

설치가 안 되어 있다면:
- **macOS (Homebrew 사용 시):** `brew install git`
- **macOS (Homebrew 미사용):** `xcode-select --install` 실행 (Xcode Command Line Tools 자동 설치)
- **Windows:** [git-scm.com](https://git-scm.com/) 에서 다운로드

---

## 설치 완료 체크리스트

```bash
# 터미널에서 한 번에 확인
node --version && npm --version && pnpm --version && git --version
```

- [ ] Cursor 설치 및 로그인
- [ ] Node.js 22 LTS 설치
- [ ] pnpm 설치
- [ ] Git 확인

모두 완료했다면 다음 챕터 **준비 — 서비스 기획서 작성**으로 이동하세요!

---

## 유튜브 대본 기반: 설치 실패 TOP 5와 즉시 해결

2025~2026년 초보자 설치 튜토리얼 대본을 분석하면, 실패 패턴이 거의 동일합니다.

### 1) `node` 명령이 안 잡힘

증상:
- `node --version` 실행 시 command not found

원인:
- PATH 반영 전 터미널을 계속 사용

해결:
- 터미널 완전 종료 후 재실행
- macOS는 `~/.zshrc` 또는 `~/.zprofile`에 경로 반영 여부 확인

### 2) `npm`은 되는데 `pnpm`이 안 됨

증상:
- `pnpm --version` 실패

원인:
- 전역 설치 누락 또는 shell 캐시 문제

해결:
```bash
npm install -g pnpm
hash -r
pnpm --version
```

### 3) 프로젝트 생성은 됐는데 실행이 안 됨

증상:
- `pnpm dev` 시 의존성 관련 오류

원인:
- 프로젝트 폴더에서 `pnpm install` 누락

해결:
```bash
pnpm install
pnpm dev
```

### 4) Git 연동 전에 파일이 섞임

증상:
- 어떤 파일이 변경됐는지 추적 어려움

원인:
- 첫 커밋 없이 바로 기능 구현 시작

해결:
- 프로젝트 생성 직후 `git init` + 첫 커밋으로 기준점 생성

### 5) 도구 버전이 튜토리얼과 달라 동작 차이 발생

증상:
- UI/명령 옵션이 영상과 다르게 보임

원인:
- 버전 차이

해결:
- 영상 그대로 따라하기보다 **원칙(설치→버전확인→첫 실행)** 중심으로 진행

### 설치 품질 게이트 (권장)

아래가 한 줄로 통과되면 다음 챕터로 이동하세요.

```bash
node --version && npm --version && pnpm --version && git --version
```

<h1>설치</h1>
<blockquote>
<p><strong>이 챕터를 마치면</strong> Cursor, Node.js, pnpm을 설치하고 바이브코딩을 시작할 수 있어요.</p>
</blockquote>
<p>개발 환경을 구성해 보세요. Cursor와 Node.js를 설치하면 바이브코딩을 시작할 수 있어요.</p>
<blockquote>
<p><strong>소요 시간:</strong> 약 10~15분
<strong>지원 OS:</strong> macOS, Windows, Linux</p>
</blockquote>
<hr>
<h2>macOS 전용: Homebrew로 한 번에 설치</h2>
<p>맥 사용자라면 <strong>Homebrew</strong>로 Node.js, pnpm, Git을 터미널에서 한 번에 설치할 수 있어요. 나중에 Claude Code, Gemini CLI, Google Workspace CLI 같은 도구도 <code>brew</code>로 관리하기 편해요.</p>
<h3>Homebrew 설치 (아직 없다면)</h3>
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://brew.sh" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/homebrew-install.png" alt="Homebrew 공식 사이트 — brew.sh" className="w-full h-auto" />
  </a>
</div><p>터미널(Terminal 또는 iTerm)을 열고 아래 한 줄을 붙여 넣고 실행해요.</p>
<pre><code class="language-bash">/bin/bash -c &quot;$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)&quot;
</code></pre>
<p>설치가 끝나면 터미널에 나오는 <strong>&quot;Next steps&quot;</strong> 안내대로 <code>brew</code>를 PATH에 넣어줘요. (예: <code>echo &#39;eval &quot;$(/opt/homebrew/bin/brew shellenv)&quot;&#39; &gt;&gt; ~/.zprofile</code> 후 터미널 재시작)</p>
<p>설치 확인:</p>
<pre><code class="language-bash">brew --version
# Homebrew 4.x.x
</code></pre>
<h3>Homebrew로 Node.js · pnpm · Git 설치</h3>
<p>아래 명령어만 실행하면 돼요.</p>
<pre><code class="language-bash"># Node.js (LTS)
brew install node@22

# PATH에 node 22 넣기 (Apple Silicon 기준)
echo &#39;export PATH=&quot;/opt/homebrew/opt/node@22/bin:$PATH&quot;&#39; &gt;&gt; ~/.zshrc
source ~/.zshrc

# pnpm (전역)
npm install -g pnpm

# Git (이미 Xcode CLI에 있을 수 있음)
brew install git
</code></pre>
<p>확인:</p>
<pre><code class="language-bash">node --version   # v22.x.x
pnpm --version  # 9.x 이상
git --version   # 2.x.x
</code></pre>
<h3>Homebrew로 그 밖의 도구 설치 (선택)</h3>
<p>이 커리큘럼에서 나중에 쓰는 CLI 도구들도 <code>brew</code>로 설치할 수 있어요.</p>
<table>
<thead>
<tr>
<th>도구</th>
<th>설치 명령</th>
<th>비고</th>
</tr>
</thead>
<tbody><tr>
<td><strong>Claude Code</strong></td>
<td><code>brew install anthropic-ai/tap/claude-code</code></td>
<td>공식 tap</td>
</tr>
<tr>
<td><strong>Gemini CLI</strong></td>
<td><code>npm install -g @google/gemini-cli</code></td>
<td>npm 권장</td>
</tr>
<tr>
<td><strong>Google Workspace CLI (gws)</strong></td>
<td><code>npm install -g @googleworkspace/cli</code></td>
<td>npm 권장</td>
</tr>
<tr>
<td><strong>pnpm</strong></td>
<td><code>brew install pnpm</code></td>
<td>또는 <code>npm i -g pnpm</code></td>
</tr>
</tbody></table>
<blockquote>
<p><strong>참고:</strong> Cursor는 GUI 앱이라 <a href="https://www.cursor.com/downloads">cursor.com/downloads</a>에서 다운로드하는 방식을 권장해요. <code>brew install --cask cursor</code> 로도 설치 가능해요.</p>
</blockquote>
<hr>
<h2>1. <a href="https://www.cursor.com/downloads">Cursor</a></h2>
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://www.cursor.com/downloads" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/cursor-download.png" alt="Cursor 공식 다운로드 — Download for your OS" className="w-full h-auto" />
  </a>
</div><p>AI 코딩 에디터 Cursor를 설치해 보세요.</p>
<p><code>Download for [현재 컴퓨터의 운영체제]</code> 버튼을 눌러서 다운받아 보세요. (<a href="https://www.cursor.com/downloads">다운로드 페이지</a>)</p>
<p>설치 후 처음 실행 시:</p>
<ol>
<li><a href="https://www.cursor.com/downloads">Continue with GitHub</a> 로그인</li>
<li>에디터 테마 선택 (Dark 권장)</li>
<li>키바인딩 설정 (VS Code 사용자는 VS Code 선택)</li>
</ol>
<blockquote>
<p><strong>2026 기준 최신 버전:</strong> Cursor 0.47+ | AI 모델: Claude 3.7 Sonnet, GPT-4o, Gemini 2.0 Flash</p>
</blockquote>
<h3>Cursor 첫 설정</h3>
<p>설치 후 아래 설정을 확인하세요:</p>
<ul>
<li><strong>설정 열기:</strong> <code>Cmd+,</code> (macOS) / <code>Ctrl+,</code> (Windows)</li>
<li><strong>AI 모델:</strong> <code>claude-3-7-sonnet</code> 권장 (코드 이해력 최고)</li>
<li><strong>자동완성:</strong> Tab 키로 수락, Esc 키로 거절</li>
</ul>
<hr>
<h2>2. <a href="https://nodejs.org/ko">Node.js</a> (LTS)</h2>
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://nodejs.org/ko" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/nodejs-download.png" alt="Node.js 공식 사이트 — Run JavaScript Everywhere, Get Node.js 다운로드" className="w-full h-auto" />
  </a>
</div><p>JavaScript 런타임 환경입니다. Next.js 앱 실행과 패키지 관리에 필요합니다.</p>
<p><a href="https://nodejs.org/ko">Node.js 다운로드 (LTS)</a> 버튼을 눌러서 다운로드 받아주세요.</p>
<blockquote>
<p><strong>2026 기준 LTS:</strong> Node.js 22.x (추천) — 짝수 버전이 LTS입니다.</p>
</blockquote>
<p>설치 확인 (터미널에서):</p>
<pre><code class="language-bash">node --version
# v22.x.x 이상이면 정상

npm --version
# 10.x.x 이상이면 정상
</code></pre>
<hr>
<h2>3. pnpm 설치</h2>
<p>빠르고 효율적인 패키지 매니저입니다. npm보다 설치 속도가 2~3배 빠르고 디스크 공간을 절약합니다.</p>
<p>터미널을 열고 아래 명령어를 실행하세요:</p>
<pre><code class="language-bash">npm install -g pnpm
</code></pre>
<p>설치 확인:</p>
<pre><code class="language-bash">pnpm --version
# 9.x.x 이상이면 정상
</code></pre>
<blockquote>
<p><strong>pnpm vs npm:</strong></p>
<ul>
<li><code>npm install</code> → <code>pnpm install</code></li>
<li><code>npm run dev</code> → <code>pnpm dev</code></li>
<li><code>npm install [패키지]</code> → <code>pnpm add [패키지]</code></li>
</ul>
</blockquote>
<hr>
<h2>4. Git 확인</h2>
<div className="float-right w-full md:w-[40%] md:ml-6 mb-4 flex-shrink-0 not-prose">
  <a href="https://git-scm.com/" target="_blank" rel="noopener noreferrer" className="block rounded-lg overflow-hidden border border-slate-200 shadow-sm hover:shadow-md transition-shadow">
    <img src="/images/git-download.png" alt="Git 공식 사이트 — git-scm.com 다운로드" className="w-full h-auto" />
  </a>
</div><p>GitHub 연동에 필요한 Git이 설치되어 있는지 확인합니다.</p>
<pre><code class="language-bash">git --version
# git version 2.x.x 이상이면 정상
</code></pre>
<p>설치가 안 되어 있다면:</p>
<ul>
<li><strong>macOS (Homebrew 사용 시):</strong> <code>brew install git</code></li>
<li><strong>macOS (Homebrew 미사용):</strong> <code>xcode-select --install</code> 실행 (Xcode Command Line Tools 자동 설치)</li>
<li><strong>Windows:</strong> <a href="https://git-scm.com/">git-scm.com</a> 에서 다운로드</li>
</ul>
<hr>
<h2>설치 완료 체크리스트</h2>
<pre><code class="language-bash"># 터미널에서 한 번에 확인
node --version &amp;&amp; npm --version &amp;&amp; pnpm --version &amp;&amp; git --version
</code></pre>
<ul>
<li><input disabled="" type="checkbox"> Cursor 설치 및 로그인</li>
<li><input disabled="" type="checkbox"> Node.js 22 LTS 설치</li>
<li><input disabled="" type="checkbox"> pnpm 설치</li>
<li><input disabled="" type="checkbox"> Git 확인</li>
</ul>
<p>모두 완료했다면 다음 챕터 <strong>준비 — 서비스 기획서 작성</strong>으로 이동하세요!</p>
<hr>
<h2>유튜브 대본 기반: 설치 실패 TOP 5와 즉시 해결</h2>
<p>2025~2026년 초보자 설치 튜토리얼 대본을 분석하면, 실패 패턴이 거의 동일합니다.</p>
<h3>1) <code>node</code> 명령이 안 잡힘</h3>
<p>증상:</p>
<ul>
<li><code>node --version</code> 실행 시 command not found</li>
</ul>
<p>원인:</p>
<ul>
<li>PATH 반영 전 터미널을 계속 사용</li>
</ul>
<p>해결:</p>
<ul>
<li>터미널 완전 종료 후 재실행</li>
<li>macOS는 <code>~/.zshrc</code> 또는 <code>~/.zprofile</code>에 경로 반영 여부 확인</li>
</ul>
<h3>2) <code>npm</code>은 되는데 <code>pnpm</code>이 안 됨</h3>
<p>증상:</p>
<ul>
<li><code>pnpm --version</code> 실패</li>
</ul>
<p>원인:</p>
<ul>
<li>전역 설치 누락 또는 shell 캐시 문제</li>
</ul>
<p>해결:</p>
<pre><code class="language-bash">npm install -g pnpm
hash -r
pnpm --version
</code></pre>
<h3>3) 프로젝트 생성은 됐는데 실행이 안 됨</h3>
<p>증상:</p>
<ul>
<li><code>pnpm dev</code> 시 의존성 관련 오류</li>
</ul>
<p>원인:</p>
<ul>
<li>프로젝트 폴더에서 <code>pnpm install</code> 누락</li>
</ul>
<p>해결:</p>
<pre><code class="language-bash">pnpm install
pnpm dev
</code></pre>
<h3>4) Git 연동 전에 파일이 섞임</h3>
<p>증상:</p>
<ul>
<li>어떤 파일이 변경됐는지 추적 어려움</li>
</ul>
<p>원인:</p>
<ul>
<li>첫 커밋 없이 바로 기능 구현 시작</li>
</ul>
<p>해결:</p>
<ul>
<li>프로젝트 생성 직후 <code>git init</code> + 첫 커밋으로 기준점 생성</li>
</ul>
<h3>5) 도구 버전이 튜토리얼과 달라 동작 차이 발생</h3>
<p>증상:</p>
<ul>
<li>UI/명령 옵션이 영상과 다르게 보임</li>
</ul>
<p>원인:</p>
<ul>
<li>버전 차이</li>
</ul>
<p>해결:</p>
<ul>
<li>영상 그대로 따라하기보다 <strong>원칙(설치→버전확인→첫 실행)</strong> 중심으로 진행</li>
</ul>
<h3>설치 품질 게이트 (권장)</h3>
<p>아래가 한 줄로 통과되면 다음 챕터로 이동하세요.</p>
<pre><code class="language-bash">node --version &amp;&amp; npm --version &amp;&amp; pnpm --version &amp;&amp; git --version
</code></pre>