00 사전 준비

Python, Node.js 설치(Windows기준)

참고자료

윈도우즈에서 클로드코드 사용하기

https://www.gpters.org/nocode/post/use-claude-code-windows-gIm094mozPmqsTK

🛠 사전 설치 가이드 (Windows) - AI 생성

Post-Note 프로젝트를 실행하기 위한 Windows 개발 환경 설정

---

필수 소프트웨어

소프트웨어	최소 버전	용도	다운로드
Python	3.10+	Backend (FastAPI 서버)	python.org
Node.js	18+	Frontend (Next.js 서버)	nodejs.org

---

1. Python 설치

Step 1: 설치 파일 다운로드

https://www.python.org/downloads/ 에 접속하여 “Download Python 3.12.x” 버튼을 클릭합니다.

https://www.python.org/ftp/python/3.12.10/python-3.12.10-amd64.exe

Step 2: 설치 실행

다운로드된 .exe 파일을 실행하고, 아래 순서대로 진행합니다:

⚠️ 중요: 반드시 아래 두 항목을 체크하세요!

☑ Use admin privileges when installing py.exe
☑ Add python.exe to PATH    ← 이것을 반드시 체크!!!

→ [Install Now] 클릭

“Add python.exe to PATH”를 체크하지 않으면 명령 프롬프트에서 python 명령어가 인식되지 않습니다. 만약 체크하지 않고 설치했다면, Python을 삭제 후 다시 설치하는 것이 가장 빠릅니다.

Step 3: 설치 확인

명령 프롬프트(cmd) 또는 PowerShell을 새로 열고 다음을 입력합니다:

python --version

정상 출력:

Python 3.12.8

pip도 확인합니다:

pip --version

정상 출력:

pip 24.3.1 from C:\Python312\Lib\site-packages\pip (python 3.12)

🔧 트러블슈팅: python이 인식되지 않을 때

1. 설치 시 PATH 체크를 누락한 경우 → Python 재설치 (이번에는 반드시 체크)
2. 터미널을 재시작하지 않은 경우 → cmd/PowerShell을 닫고 새로 열기
3. Windows Store 버전이 실행되는 경우:

   # Windows 설정 → 앱 → 앱 실행 별칭
   # "python.exe" 와 "python3.exe" 별칭을 끄기

---

2. Node.js 설치

Step 1: 설치 파일 다운로드

https://nodejs.org/ 에 접속하여 LTS (Long Term Support) 버전을 다운로드합니다.

┌─────────────────────────────┐
│  ✅ 22.x.x LTS  (권장)      │  ← 이것을 클릭
│     Most users에 적합        │
├─────────────────────────────┤
│  Current 23.x.x             │  ← 이것은 패스
│     최신 기능, 불안정할 수 있음 │
└─────────────────────────────┘

Step 2: 설치 실행

다운로드된 .msi 파일을 실행하고 기본 설정 그대로 Next를 클릭하여 설치합니다.

[Next] → [Next] → [Next] → [Install] → [Finish]

별도 설정 변경 없이 기본값으로 설치하면 됩니다. Node.js 설치 시 npm이 함께 설치됩니다.

Step 3: 설치 확인

명령 프롬프트를 새로 열고 다음을 입력합니다:

node --version

정상 출력:

v22.14.0

npm도 확인합니다:

npm --version

정상 출력:

10.9.2

🔧 트러블슈팅: node가 인식되지 않을 때

1. 터미널을 새로 열었는지 확인 (설치 전에 열어둔 터미널에서는 인식 안 됨)
2. 그래도 안 되면 → PC 재부팅 후 다시 시도
3. 여전히 안 되면 → Node.js 재설치

---

3. 전체 설치 검증

모든 소프트웨어가 정상 설치되었는지 한 번에 확인합니다.

명령 프롬프트를 열고 다음을 실행하세요:

python --version && pip --version && node --version && npm --version

정상 출력 예시:

Python 3.12.8
pip 24.3.1 from C:\Python312\Lib\site-packages\pip (python 3.12)
v22.14.0
10.9.2

4줄 모두 버전 정보가 출력되면 설치가 완료된 것입니다! ✅

---

4. 자주 묻는 질문 (FAQ)

Q: pip install 시 인코딩 에러가 발생해요 (cp949 관련)

A: 환경변수 설정 후 다시 실행하세요:

set PYTHONUTF8=1
pip install -r requirements.txt

Q: pip install 시 권한(Permission) 에러가 나요

A: 관리자 권한으로 cmd를 실행하거나, --user 옵션을 추가하세요:

pip install --user -r requirements.txt

Q: npm install 시 에러가 발생해요

A: 캐시를 정리하고 다시 시도하세요:

npm cache clean --force
npm install

Q: 포트가 이미 사용 중이라는 에러가 나요

A: 해당 포트를 사용하는 프로세스를 종료하세요:

# 포트 3000을 사용하는 프로세스 확인
netstat -ano | findstr :3000

# 해당 PID의 프로세스 종료
taskkill /PID <PID번호> /F

Q: Python 가상환경(venv)을 사용하고 싶어요

A: 프로젝트 격리를 위해 가상환경 사용을 권장합니다:

cd backend

# 가상환경 생성
python -m venv venv

# 가상환경 활성화
venv\Scripts\activate

# 패키지 설치
pip install -r requirements.txt

# (작업 종료 후) 가상환경 비활성화
deactivate