blog › posts › 06-자주-막히는-문제-해결-가이드.md

06. 자주 막히는 문제 해결 가이드

“에러는 적이 아니라 신호다. 어디가 잘못됐는지 알려주는.”

이것을 왜 배우는가?

블로그 셋업·운영 중 99%의 사람이 막히는 패턴이 있습니다. 같은 함정을 미리 알면 1시간 헤맬 일을 5분에 끝낼 수 있습니다.

이 문서는 참고용입니다. 처음부터 끝까지 읽지 말고, 본인이 막힌 상황과 비슷한 항목을 검색하세요.

문제 분류

분류	자주 발생 시점
1. 환경 설정 문제	처음 설치 시
2. Astro 빌드 에러	코드 수정 후
3. Git/GitHub 문제	git push 시
4. Cloudflare 배포 실패	배포 후
5. 사이트 표시 문제	글 추가 후
6. AdSense 문제	광고 추가 후

1. 환경 설정 문제

1-1. `node: command not found` / `npm: command not found`

증상: 터미널에서 node·npm 명령어 실행 시 “찾을 수 없음” 에러.

원인: Node.js 설치 안 됐거나 PATH 환경변수에 등록 안 됨.

해결 순서:

# (1) Node.js 설치 확인
which node           # Mac/Linux
where node           # Windows
# 경로가 안 나오면 미설치

# (2) Node.js 재설치
# https://nodejs.org에서 LTS 버전 다운로드 → 설치

# (3) 터미널 닫고 새로 열기 (PATH 인식)

# (4) 그래도 안 되면 컴퓨터 재부팅

✅ node --version 으로 v22.x.x 같은 게 출력되면 OK.

1-2. `git: command not found`

증상: git 명령어 실행 시 “찾을 수 없음”.

Mac:

# Xcode Command Line Tools 설치
xcode-select --install
# 권한 묻는 창 뜨면 "Install" 클릭, 5~10분 대기

Windows:

# https://git-scm.com 에서 Windows용 다운로드
# 설치 시 "Add Git to PATH" 체크 확인

설치 후 터미널 재시작.

1-3. Permission denied (npm install 시)

증상: npm install 시 EACCES: permission denied.

원인: 시스템 npm 폴더에 권한 없음 (보통 Mac).

해결:

# 방법 1 (Mac, 권장): nvm 사용해서 사용자 권한으로 Node.js 관리
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash
nvm install --lts

# 방법 2: 권한 변경 (덜 안전)
sudo chown -R $(whoami) ~/.npm

⚠️ sudo npm install은 비권장. 권한 문제 임시방편이지만 보안 약화.

2. Astro 빌드 에러

2-1. `Cannot find module 'astro'`

증상: npm run dev 실행 시 “astro 모듈을 찾을 수 없음”.

원인: node_modules/ 폴더 없음 (의존 패키지 설치 안 됨).

해결:

cd my-blog
npm install
# 또는
rm -rf node_modules package-lock.json
npm install

2-2. Frontmatter 파싱 에러

증상: 빌드 시 Invalid frontmatter 또는 YAML parsing error.

원인: 글의 Frontmatter 형식 틀림.

자주 발생하는 패턴:

❌ 잘못된 예:

---
title: 글의 제목 : 부제목     ← 콜론(:)이 값 안에 있음
pubDate: 2026-04-29           ← 따옴표 없음 (날짜는 따옴표 권장)
description:짧은 설명         ← 콜론 뒤 공백 없음
---

✅ 올바른 예:

---
title: '글의 제목 : 부제목'
pubDate: '2026-04-29'
description: '짧은 설명'
---

해결 원칙:

콜론(:) 포함 값은 반드시 따옴표로 감싸기
콜론 뒤에 공백 1개
날짜·숫자 값도 따옴표 권장

2-3. `[InvalidContentEntryDataError]`

증상: 글 빌드 시 “콘텐츠 데이터가 schema와 맞지 않음”.

원인: src/content.config.ts에 정의된 필수 필드가 빠짐.

해결:

src/content.config.ts 열어서 schema 확인:

import { defineCollection, z } from 'astro:content';
import { glob } from 'astro/loaders';

const blog = defineCollection({
	loader: glob({ base: './src/content/blog', pattern: '**/*.{md,mdx}' }),
	schema: z.object({
		title: z.string(),         // 필수
		description: z.string(),    // 필수
		pubDate: z.coerce.date(),   // 필수
		updatedDate: z.coerce.date().optional(),
		heroImage: z.string().optional(),
	}),
});

export const collections = { blog };

→ 이 schema에 정의된 필수 필드(title, description, pubDate)가 글 Frontmatter에 다 있어야 함.

2-4. 이미지가 깨짐

증상: 글에 넣은 이미지가 안 보이거나 X 표시.

원인 + 해결:

원인	해결
`public/` 안에 파일 없음	`public/images/foo.png` 위치에 파일 둠
경로 잘못 씀 (`/images/foo.png` 대신 `images/foo.png`)	`/`로 시작 (절대 경로)
파일 이름에 공백/한글	영문 + 하이픈만
확장자 대소문자 불일치 (`foo.PNG` vs `foo.png`)	정확히 일치

✅ 올바른 예:

![캡션](/images/screenshot.png)

파일 위치: public/images/screenshot.png

3. Git/GitHub 문제

3-1. `Permission denied (publickey)` 또는 `fatal: Authentication failed`

증상: git push 시 인증 실패.

원인: GitHub이 일반 비밀번호 차단.

해결 (3가지 방법):

방법 A: 브라우저 인증 (가장 쉬움)

# 자동으로 브라우저 열림 → GitHub 로그인 → 권한 허용
git push

만약 자동으로 안 열리면:

# Git Credential Manager 설치 (Mac)
brew install --cask git-credential-manager

# Windows: Git for Windows 설치 시 자동 포함

방법 B: Personal Access Token (PAT)

GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic) → “Generate new token”
Scopes: repo 전체 체크
생성된 토큰 복사 (한 번만 보임)
git push 시 비밀번호 자리에 토큰 붙여넣기

방법 C: SSH 키 (고급)

# SSH 키 생성
ssh-keygen -t ed25519 -C "your@email.com"

# 공개 키 복사
cat ~/.ssh/id_ed25519.pub

# GitHub → Settings → SSH and GPG keys → New SSH key → 붙여넣기

# 원격 URL 변경 (https → ssh)
git remote set-url origin git@github.com:본인아이디/my-blog.git

3-2. `error: failed to push some refs`

증상: git push 시 “Updates were rejected because the remote contains work that you do not have locally”

원인: GitHub에 본인 컴퓨터에 없는 변경사항이 있음 (보통 README 만들 때 GitHub에서 추가했을 때).

해결:

# 원격 변경사항 가져오기 (rebase 방식)
git pull --rebase origin main

# 충돌 없으면 다시 push
git push

3-3. `fatal: not a git repository`

증상: git 명령어 실행 시 “git 저장소 아님” 에러.

원인: 현재 폴더가 git 저장소가 아님.

해결:

# (1) 올바른 폴더에 있는지 확인
pwd                  # 현재 경로 출력
ls .git              # .git 폴더 있어야 git 저장소

# (2) 없으면 my-blog 폴더로 이동
cd ~/code/my-blog

# (3) 그래도 .git 없으면 다시 초기화
git init
git remote add origin https://github.com/본인아이디/my-blog.git

3-4. commit 안 한 변경사항이 사라짐

증상: 코드 수정했는데 다음 날 보니 사라짐.

원인:

VS Code 자동 저장 안 됨
git stash 후 잊어버림
branch 잘못 갈아탐

예방: 자주 commit + push 습관. 30분~1시간마다 커밋.

git add .
git commit -m "wip: in progress"  # work in progress
git push

4. Cloudflare 배포 실패

4-1. 빌드 실패: `Module not found`

증상: Cloudflare 빌드 로그에 “Cannot find module” 에러.

원인: 본인 컴퓨터엔 있는 패키지가 GitHub에 안 올라감.

해결:

# package.json에 패키지 추가됐는지 확인
cat package.json

# 없으면 다시 install + commit
npm install 패키지이름
git add .
git commit -m "fix: add missing dependency"
git push

4-2. 빌드 실패: Node.js 버전

증상: Node version mismatch 또는 Unsupported engine.

원인: Cloudflare 기본 Node 버전이 낮거나 안 맞음.

해결:

Cloudflare 대시보드 → 프로젝트 → Settings → Environment variables → 추가:

이름	값
`NODE_VERSION`	`22` (또는 본인이 로컬에서 쓰는 버전)

저장 후 다시 배포 시도 (Deployments → “Retry deployment”).

4-3. 빌드 성공했는데 사이트가 빈 화면

증상: 배포는 성공했지만 사이트 접속 시 빈 페이지.

원인: Build output directory 잘못됨.

해결:

Cloudflare Settings → Builds & deployments → Build output directory: dist (Astro 표준)
다른 값으로 돼있으면 dist로 수정

4-4. 사이트 변경이 반영 안 됨 (캐시)

증상: git push 했는데 사이트가 옛날 상태.

원인: 브라우저·Cloudflare CDN 캐시.

해결:

1. 브라우저에서 강제 새로고침
   Mac: Cmd + Shift + R
   Windows: Ctrl + Shift + R

2. 그래도 안 되면 시크릿 창에서 접속

3. 그래도 안 되면 Cloudflare에서 캐시 비우기:
   Cloudflare 대시보드 → 프로젝트 → Deployments에서 빌드 완료됐는지 확인
   Caching → Configuration → "Purge Everything"

5. 사이트 표시 문제

5-1. 새 글이 메인 페이지에 안 보임

증상: 글을 추가했는데 메인 페이지 글 목록에 안 나타남.

원인 + 해결:

원인	해결
Frontmatter `pubDate` 형식 틀림	`'2026-04-29'` (따옴표 + ISO 형식)
`pubDate`가 미래 날짜	현재 또는 과거 날짜로
파일 위치 잘못 (`src/content/blog/` 밖)	정확한 경로에 두기
파일 확장자 `.md` 아님	`.md` 또는 `.mdx`로
빌드 캐시 문제	`npm run dev` 끄고 다시 켜기

5-2. 한국어 깨짐

증상: 글의 한글이 ?로 표시되거나 깨짐.

원인: 파일 인코딩 UTF-8 아님.

해결:

VS Code: 우측 하단 UTF-8 표시 클릭 → “Save with Encoding” → “UTF-8”
다른 에디터: 인코딩 UTF-8로 변경 후 재저장

5-3. 마크다운 표가 깨짐

증상: 표 작성했는데 일반 텍스트로 표시.

원인: 표 문법 정확하지 않음.

❌ 잘못:

|항목|설명|
|셀A|셀B|        ← 헤더 구분선 없음

✅ 올바름:

| 항목 | 설명 |
|------|------|
| 셀A  | 셀B  |

→ 헤더 행과 본문 사이에 |---|---| 구분선 필수.

5-4. 코드 블록 색깔(syntax highlighting) 안 나옴

증상: ```js 로 감쌌는데 색깔이 안 입혀짐.

원인: 언어 이름 잘못 또는 누락.

✅ 올바름:

```javascript
// 코드 (색깔 적용됨)
```

```python
# 파이썬
```

```bash
# 셸 명령어
```

→ ``` 뒤에 언어 이름. 흔한 이름: javascript, typescript, python, bash, html, css, json, markdown.

6-1. 신청 거절: “콘텐츠가 충분하지 않음”

원인: 글 수·길이 부족.

해결:

글 30편 이상 누적
각 글 1,500자 이상
About·Privacy Policy 페이지 명확히
1~2개월 후 재신청

6-2. 신청 거절: “Privacy Policy 없음”

해결: 05-monetize.md 참고해서 Privacy Policy 페이지 추가 후 재신청.

6-3. 광고가 안 보임

원인 + 해결:

원인	해결
`ca-pub-XXX` 자리에 인증 코드 안 바꿈	본인 받은 코드로 교체
광고 차단 프로그램(AdBlock) 작동 중	시크릿 창에서 확인
AdSense 신청 후 며칠 내 (광고 매칭 시간)	1주일 대기
광고 코드 위치 이상	본문 영역(`<article>` 안)에 배치

6-4. 광고 떠도 클릭이 안 됨

원인: AdSense는 무효 클릭 방지를 위해 본인이 본인 광고 클릭하면 차단.

⚠️ 본인 광고 절대 클릭 금지. 친구한테 부탁하는 것도 금지. 무효 클릭 패턴 감지되면 계정 정지.

7. 일반 디버깅 방법

7-1. 에러 메시지를 그대로 검색

가장 강력한 방법. 에러 메시지를 Google에 그대로 붙여넣기 → Stack Overflow·GitHub Issue에서 답 발견.

7-2. AI에 질문 (가장 빠름)

Cursor·Claude·ChatGPT에 다음 정보를 함께 전달:

[배경]
Astro 5.x로 블로그 만들고 있는 중.
Cloudflare Pages에 배포.

[문제]
git push는 됐는데 사이트가 업데이트 안 됨.

[에러 메시지]
(에러 그대로 붙여넣기)

[이미 시도한 것]
- 브라우저 강제 새로고침
- Cloudflare Deployments에서 빌드 성공 확인

이 문제 어떻게 해결?

→ 보통 정확한 답 줌.

7-3. 문제를 격리 (Minimal Reproduction)

복잡한 문제일 때:

새 폴더에 새 Astro 프로젝트 만들기
같은 문제 발생하는지 확인
발생하면 → 환경 문제. 안 발생하면 → 본인 코드 문제
본인 코드 문제면 한 줄씩 빼면서 어디가 원인인지 좁히기

7-4. 공식 docs 확인

도구	공식 문서
Astro	https://docs.astro.build
Cloudflare Pages	https://developers.cloudflare.com/pages/
GitHub	https://docs.github.com
npm	https://docs.npmjs.com

→ 영문이지만 가장 정확. AI보다 신뢰 가능.

도움 받을 수 있는 곳

채널	언제
AI (Cursor/Claude/ChatGPT)	일반 코드/설정 문제
Stack Overflow	구체적 에러 메시지 검색
GitHub Issues (Astro repo)	Astro 자체 버그 의심
Astro Discord	실시간 도움 (영문)
Cloudflare Community	Cloudflare 특화 문제
디스콰이엇	한국어 인디 개발자 도움

💡 핵심 원칙

문제 해결의 3원칙:

에러 메시지를 정확히 읽기 — 화나서 닫지 말고 진짜 무슨 말인지 파악
변수 하나만 바꾸기 — 한 번에 여러 개 고치면 어디가 원인인지 모름
막히면 30분 안에 도움 청하기 — 1시간+ 헤매지 말고 AI·검색·커뮤니티

⚠️ 블로그 셋업에 며칠씩 막히면 안 됩니다. 막히는 게 정상이지만 1~2시간 안에 풀어야 합니다. 못 풀면 AI에 질문 + 사람한테 물어보세요.

끝맺으며

이 문서는 시작일 뿐입니다. 셋업이 끝나면 진짜 어려운 건 따로입니다:

꾸준히 글 쓰기 (가장 어려움)
검색 의도에 맞는 키워드 발견
사용자가 진짜 원하는 걸 만들기
광고가 아닌 다른 수익 모델 찾기

블로그는 도구입니다. 도구가 작동하면 이제부터가 진짜 시작입니다.

다음 단계

전체 가이드 끝. 아래 행동 순서로 시작하세요:

README.md 다시 한 번 정리해서 읽기
01-prerequisites.md부터 순서대로 진행
첫 글 작성 + git push
1주일 후 두 번째 글
1개월 후 5편 누적되면 일관성 자축
글 30편 누적 시 05-monetize.md로 수익화 검토

한 줄 요약: 셋업은 2~3시간, 그 후 매주 1편씩 1년. 1년 후의 본인이 가장 큰 수혜자.

🔗 관련 자료:

06. 자주 막히는 문제 해결 가이드

이것을 왜 배우는가?

문제 분류

1. 환경 설정 문제

1-1. node: command not found / npm: command not found

1-2. git: command not found

1-3. Permission denied (npm install 시)

2. Astro 빌드 에러

2-1. Cannot find module 'astro'

2-2. Frontmatter 파싱 에러

2-3. [InvalidContentEntryDataError]

2-4. 이미지가 깨짐

3. Git/GitHub 문제

3-1. Permission denied (publickey) 또는 fatal: Authentication failed

3-2. error: failed to push some refs

3-3. fatal: not a git repository

3-4. commit 안 한 변경사항이 사라짐

4. Cloudflare 배포 실패

4-1. 빌드 실패: Module not found

4-2. 빌드 실패: Node.js 버전

4-3. 빌드 성공했는데 사이트가 빈 화면

4-4. 사이트 변경이 반영 안 됨 (캐시)

5. 사이트 표시 문제

5-1. 새 글이 메인 페이지에 안 보임

5-2. 한국어 깨짐

5-3. 마크다운 표가 깨짐

5-4. 코드 블록 색깔(syntax highlighting) 안 나옴

6. AdSense 문제

6-1. 신청 거절: “콘텐츠가 충분하지 않음”

6-2. 신청 거절: “Privacy Policy 없음”

6-3. 광고가 안 보임

6-4. 광고 떠도 클릭이 안 됨

7. 일반 디버깅 방법

7-1. 에러 메시지를 그대로 검색

7-2. AI에 질문 (가장 빠름)

7-3. 문제를 격리 (Minimal Reproduction)

7-4. 공식 docs 확인

도움 받을 수 있는 곳

💡 핵심 원칙

끝맺으며

다음 단계

1-1. `node: command not found` / `npm: command not found`

1-2. `git: command not found`

2-1. `Cannot find module 'astro'`

2-3. `[InvalidContentEntryDataError]`

3-1. `Permission denied (publickey)` 또는 `fatal: Authentication failed`

3-2. `error: failed to push some refs`

3-3. `fatal: not a git repository`

4-1. 빌드 실패: `Module not found`