자주 묻는 질문과 문제 해결 FAQ

최종 업데이트: 2026. 9. 22. / EpoCanvas 공식 아키텍처 사양

EpoCanvas Docs를 사용하거나, 작성하거나, 배포하는 과정에서 이상을 만났을 때는 먼저 여기서 해당하는 항목을 찾아보세요. 문제는 “로컬 실행 → 문서 작성 → 검색 → 배포” 순서로 배열되어 있으며, 각 문제마다 원인과 검증된 해결 방법을 제시합니다.

1. 로컬 실행 및 설치 문제

Q1: `pnpm run dev` 실행 시 포트 4321가 이미 사용 중이라고 표시됨

원인: 이전에 실행한 개발 서버가 완전히 종료되지 않았거나, 다른 프로그램이 4321 포트를 사용 중입니다.
해결 방법: 다른 포트로 실행합니다:
Terminal window
```
pnpm run dev -- --port 4322
```

Q2: 의존성 설치 시 Sharp 모듈 컴파일 오류가 표시됨

원인: Sharp는 빌드 시점에 이미지를 압축하는 하부 C++ 모듈로, Node.js 버전이 바뀌면 예전 캐시와 맞지 않을 수 있습니다.
해결 방법: 의존성을 정리한 후 다시 설치합니다:
Terminal window
```
rm -rf node_modules pnpm-lock.yaml
pnpm install
```

Q3: `pnpm install` 실행 시 `packages field missing or empty` 오류가 발생함

원인: pnpm-workspace.yaml 내용이 비어 있거나 형식이 불완전하여, pnpm이 이를 워크스페이스 설정 파일로 해석하며 오류를 냅니다.
해결 방법: 파일에 packages 필드가 포함되어 있는지 확인합니다:
```
packages:
  - .
```

2. 문서 작성 및 렌더링 문제

Q4: 새 Markdown 파일을 만들었는데 왼쪽 사이드바에 보이지 않음

원인: 사이드바 목차는 수동으로 선언하는 방식이라 새 파일은 반드시 설정에 등록해야 합니다.
해결 방법: astro.config.mjs를 열어 sidebar 배열의 적절한 그룹 아래에 추가합니다:
```
{ label: '새 기능 설명', link: '/canvas/new-feature/' }
```

Q5: 터미널에 `"title" is required` 오류가 표시됨

원인: Markdown 머리 부분에서 title을 누락했거나, 맨 앞의 세 개 가로줄 --- 형식이 올바르지 않습니다.
해결 방법: 파일 맨 위의 Frontmatter를 확인합니다:
```
---
title: 문서 제목
description: 문서 설명
---
```

Q6: 페이지에 똑같은 대제목이 두 개 나타남

원인: 본문에 수준 1 제목 #을 또 썼습니다. Frontmatter의 title이 이미 대제목으로 렌더링되므로 본문에 #을 쓰면 반드시 중복됩니다.
해결 방법: 본문의 # 제목을 삭제하고 소제목은 ##부터 시작합니다. 전체 규칙은 렌더링 규칙 상세를 참조하세요.

Q7: `> [!TIP]`을 썼는데 콜아웃이 색이 변하지 않고 글자가 그대로 표시됨

원인: GitHub 스타일의 > [!TIP] 인용 블록 문법은 지원되지 않으며, Markdown 컴파일러가 인식하지 못합니다.
해결 방법: 세 개의 콜론 문법으로 바꿉니다:
```
:::tip
올바른 작성 방법입니다.
:::
```

Q8: 삽입한 이미지가 깨진 그림으로 표시됨

원인: 이미지 경로가 잘못되었거나, 이미지를 public/ 정적 디렉터리에 넣지 않았습니다.
해결 방법:
1. 이미지가 public/images/canvas/ui-docs-reading.png에 저장되어 있는지 확인합니다;
2. 참조할 때는 /로 시작하는 절대 경로를 사용합니다: ![설명](/images/canvas/ui-docs-reading.png), ../public/... 같은 상대 경로는 쓰지 않습니다.

3. 검색 기능 문제

Q9: 로컬에서 `pnpm dev`로 디버깅할 때 전역 검색으로 방금 쓴 새 글이 검색되지 않음

원인: 사이트 전체 검색은 빌드 시 생성되는 Pagefind 인덱스에 의존합니다. 개발 모드에서는 Ctrl+K 대화상자가 인덱스를 불러오지 않아(열어도 검색 입력창이 없음) 전역 검색을 사용할 수 없습니다. 프레임워크의 의도된 동작이며 사이트 결함이 아닙니다.
해결 방법: 완전히 빌드한 후 미리보기 서버로 검증합니다:
Terminal window
```
pnpm run build
pnpm run preview
```
상단 바의 페이지 내 찾기는 이 제한을 받지 않으므로, 개발할 때 현재 페이지 내용을 찾는 데 바로 사용할 수 있습니다.

Q10: `Ctrl+K`를 눌러도 검색 팝업이 열리지 않음

원인: 일부 입력기, 클립보드 도구 또는 스크린샷 소프트웨어가 Ctrl+K / Cmd+K 단축키를 사용 중입니다.
해결 방법: 검색창 오른쪽의 Ctrl K 작은 배지를 직접 클릭해도 사이트 전체 검색 팝업을 열 수 있습니다.

4. Cloudflare Pages 배포 문제

Q11: 방금 연결한 커스텀 도메인에서 SSL 핸드셰이크 실패(Error 525)가 표시됨

원인: Cloudflare가 새 도메인에 Universal SSL 인증서를 발급하는 데는 보통 2~5분의 전 세계 적용 시간이 필요합니다.
해결 방법: 몇 분 기다린 후 강제 새로 고침(Ctrl+F5 / Cmd+Shift+R)합니다. 그동안은 <프로젝트명>.pages.dev 기본 도메인으로 먼저 접근할 수 있으며 항상 사용할 수 있습니다.

Q12: `pnpm run deploy` 실행 시 `Project not found` 오류가 발생함

원인: 배포 명령어의 --project-name 매개변수가 Cloudflare 콘솔의 프로젝트 이름과 일치하지 않거나, 이 컴퓨터에서 로그인하지 않았을 수 있습니다.
해결 방법:
1. 먼저 npx wrangler whoami로 로그인 여부를 확인합니다;
2. Cloudflare 콘솔에서 프로젝트 이름을 확인하고, 필요하면 package.json의 deploy 스크립트에서 --project-name 매개변수를 수정합니다.

5. 제출 전 로컬 자가 점검

GitHub에 푸시하기 전에 다음 명령어를 실행해 한 번 완전히 점검합니다(타입 검사 + 전체 빌드):

pnpm exec astro check && pnpm run build

astro check가 0 errors를 출력하고 빌드가 Complete!로 끝나면 문서에 문법 오류가 없다는 뜻이므로 안심하고 커밋할 수 있습니다. 저장소의 CI(build.yml)는 푸시 후 동일한 빌드를 실행하므로, 로컬에서 먼저 통과하면 CI 실패를 피할 수 있습니다.