문서 / 레퍼런스
이 문서의 큐
배포한 파일은 대부분 그대로 서빙됩니다. 다만 몇 개의 주소는 플랫폼이 먼저 가져갑니다. 거기에 파일을 올리면 업로드는 성공하는데 열어 보면 404 입니다.
이 문서는 그 주소를 전부 적습니다. 피해서 만들면 됩니다.
판정 표기 — 플랫폼: 배포한 파일이 절대 안 나갑니다 · 내 파일: 배포본이 이깁니다
1. 파일이 도달하지 못하는 주소
| 주소 | 매칭 | 실제 응답 | 판정 |
|---|---|---|---|
/_next · /_next/… | 경로 경계 | 플랫폼 자산 또는 404 | 플랫폼 |
/api · /api/… | 경로 경계 | 404 | 플랫폼 |
/_frozen/… | 접두 | 플랫폼 자산 또는 404 | 플랫폼 |
/turnstile/frame | 정확히 일치 | 스팸차단 위젯 프레임 | 플랫폼 |
/.well-known/oauth-protected-resource 및 그 하위 | 경로 경계 | OAuth 메타데이터 JSON | 플랫폼 |
/.well-known/… (그 밖) | — | 배포본 서빙 | 내 파일 |
✅ 이름이 그 접두로 시작하기만 하는 주소는 이제 영향받지 않습니다 (2026-08-06 수정)./api-docs.html·/apiary/index.html·/_nextdoor.html은 배포한 파일이 그대로 나갑니다. 예약되는 것은/api자신과/api/…처럼/로 끊기는 하위 경로뿐입니다.
2. 사이트 밖으로 나가는 주소
| 주소 | 호스트 | 동작 | 판정 |
|---|---|---|---|
/sites/… | <주소>.saeroon.com | 404 | 플랫폼 |
/sites/{a}/{b} | 커스텀 도메인 | 301 → https://{a}.saeroon.com/{b} | 플랫폼 |
/admin · /admin/… | <주소>.saeroon.com | 301 → 대시보드 | 플랫폼 |
/admin… | 커스텀 도메인 | 배포본 서빙 | 내 파일 |
✅/administration/·/adminx.html은 이제 배포본이 나갑니다 (2026-08-06 수정). 예약되는 것은/admin자신과/admin/…뿐입니다. ⚠️ 다만 이 301 은 서브도메인에만 있어 커스텀 도메인과 결과가 갈립니다./admin이라는 이름 자체는 여전히 피하세요.
3. 요청 주소와 파일 경로가 달라지는 규칙
| 요청 | 어떻게 되나 | 결과 |
|---|---|---|
/ko/… /en/… /ja/… 등 언어 코드 | 다국어를 켠 사이트에서만 맨 앞 언어 코드가 떨어져 나감 | 켜지 않았으면 en/ 폴더가 그대로 열립니다 |
/foo.html | 확장자 없는 주소로 301 | /foo |
/foo/ | 308 | /foo |
/foo (확장자 없음) | foo/index.html 을 찾음 | 확장자 없는 파일은 서빙할 수 없습니다 |
✅ 언어 코드 폴더가 열립니다 (2026-08-06 수정). 전에는 다국어 설정과 무관하게/en/…/ko/…의 맨 앞 조각이 항상 떨어져 나가, 최상위en/폴더를 어떤 주소로도 열 수 없었습니다. 지금은 다국어를 켠 사이트에서만 그 해석이 일어납니다. ✅/{32~64자 16진수}.txt특별취급도 없어졌습니다 (2026-08-06 수정). 전에는 IndexNow 키 파일로 해석돼 항상 404 였습니다. 이제 그 이름의 파일도 배포본 그대로 나갑니다 — IndexNow 를 쓴다면 대시보드에 넣은 키와 같은 이름의.txt를 배포 폴더에 직접 두세요.
4. 배포본이 이기는 주소 (오해 방지)
| 주소 | 동작 |
|---|---|
/robots.txt | 올렸으면 그 파일. 없을 때만 플랫폼이 자동 생성 |
/sitemap.xml | 위와 같음 (자동 생성분은 noindex 페이지를 제외합니다) |
/llms.txt | 올린 파일만. 없으면 404 (자동 생성 없음) |
/404.html | 루트에 두면 없는 주소의 응답 본문으로 씁니다 |
/favicon.ico | 올린 파일이 나갑니다 |
/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. 동작이 바뀌면 그쪽이 먼저 깨집니다.
빠진 것을 발견하면 알려 주세요. 이 목록에 없는데 파일이 안 나가는 주소가 있다면 그건 결함입니다.
요약
배포한 파일은 대부분 그대로 서빙됩니다. 다만 몇 개의 주소는 플랫폼이 먼저 가져갑니다. 거기에 파일을 올리면 업로드는 성공하는데 열어 보면 404 입니다.