배포한 파일은 대부분 그대로 서빙됩니다. 다만 몇 개의 주소는 플랫폼이 먼저 가져갑니다. 거기에 파일을 올리면 업로드는 성공하는데 열어 보면 404 입니다.

이 문서는 그 주소를 전부 적습니다. 피해서 만들면 됩니다.

판정 표기 — 플랫폼: 배포한 파일이 절대 안 나갑니다 · 내 파일: 배포본이 이깁니다

---

1. 파일이 도달하지 못하는 주소

⚠️ /api 는 경계 검사가 없습니다. /api-docs.html · /apiary/index.html 처럼 /api 로 시작만 해도 함께 잡힙니다. /_next 도 같습니다(/_nextdoor.html). 최상위에 그 이름으로 시작하는 폴더·파일을 두지 마세요.

2. 사이트 밖으로 나가는 주소

⚠️ 서브도메인에서는 /administration/ · /adminx.html 도 함께 301 됩니다. 그리고 이 동작은 서브도메인에만 있어 커스텀 도메인과 결과가 갈립니다.

3. 요청 주소와 파일 경로가 달라지는 규칙

🔴 언어 코드는 최상위 폴더 이름으로 쓰지 마세요. 다국어 설정을 켜지 않아도 규칙이 적용됩니다.

4. 배포본이 이기는 주소 (오해 방지)

/favicon.ico 는 2026-08-06 이전에는 배포해도 404 였습니다. 지금은 정상입니다. 그 전에 우회하려고 favicon.svg 만 걸어 두었다면 그대로 두어도 됩니다.

5. 예약된 쿼리 파라미터

플랫폼이 덮어씁니다 — 같은 이름을 쓰면 내 값이 사라집니다.

_locale · _whitelabel · _domain · _showLocaleBanner · _suggestedLocale · _bannerStyle

읽기 전용으로 해석되는 것: _draft=1 · _preview=1 · saeroon-banner

6. 그 밖의 제약

• GET 요청만 받습니다. 사이트 주소로 보낸 POST·PUT·DELETE 는 405 입니다. 폼 제출·API 호출은 사이트 주소가 아니라 API 주소로 보내세요.
• 사이트를 보관(Archived)하면 모든 주소가 410 이 됩니다.
• 서브도메인으로 쓸 수 없는 예약어 목록은 별개입니다 — 사이트를 만들 때 알려 드립니다.

---

7. 배포한 파일은 지워지지 않습니다

⚠️ 알고 있어야 할 동작입니다.

배포는 덮어쓰기만 합니다. 지우지 않습니다.

폴더에서 파일을 지우고 다시 배포하면 새 목록에는 없지만, 그 주소는 계속 열려 있습니다. 한 번 올라간 파일을 공개 통로로 회수하는 방법은 현재 없습니다.

# 이렇게 해도 https://<주소>.saeroon.com/assets/hero-b.jpg 는 계속 200 입니다
rm assets/hero-b.jpg
npx @saeroon/cli deploy .

그래서 이렇게 하세요.

• 배포 폴더에는 공개해도 되는 것만 둡니다. 검수용 캡처·내부 문서·고객 자료를 잠깐 넣었다 빼는 습관을 만들지 마세요.
• 비밀 값(API 키·비밀번호·토큰)이 파일에 들어갔다면 이미 유출된 것으로 보고 재발급하세요. CLI 가 그런 파일을 업로드에서 빼 주지만, 전에 한 번이라도 배포했다면 그 주소는 그대로 열려 있습니다.
• 배포 전 폴더를 한 번 훑으세요. find . -type f | sort 로 충분합니다.

사이트를 통째로 지우는 것(site archive → site delete) 말고는 개별 파일을 없애는 명령이 없습니다. 파일 단위 정리 통로는 검토 중입니다.

---

이 표가 낡지 않게 하는 것

각 행은 코드의 회귀 테스트와 짝지어 있습니다 — middleware/matcher.test.ts · middleware/routing.test.ts · static-sites/[slug]/[[...path]]/r2-path.test.ts. 동작이 바뀌면 그쪽이 먼저 깨집니다.

빠진 것을 발견하면 알려 주세요. 이 목록에 없는데 파일이 안 나가는 주소가 있다면 그건 결함입니다.