사이트를 도메인 전체가 아니라 example.com/field-notes/ 아래에 두고 싶다는 것은 흔한 요구입니다. 메인 사이트는 다른 시스템이고, 블로그는 그 아래에 매달아 두는 한 부분일 뿐인 경우입니다.
Astro에서 이에 해당하는 설정은 base 한 줄뿐입니다. 그래서 우리는 이 가이드가 짧을 것이라고 생각했습니다.
그런데 새로 블로그 템플릿 사이트를 만들어 base: "/field-notes"를 설정하고, 빌드하고, 시작한 뒤, curl로 모든 주소를 눌러 보니, 한 줄짜리 설정 말고도 예상보다 많은 일이 있었습니다. 아래는 실제로 본 것들입니다.
테스트 환경: EmDash 1.4.0, Node 어댑터, SQLite, 공식 블로그 템플릿. 템플릿에 들어 있는 글 8편은 emdash seed로 넣었습니다.
export default defineConfig({
output: "server",
base: "/field-notes",
// ...
});
어떤 주소가 base를 따라 움직였나?
좋은 소식부터입니다. 페이지 자체는 문제없습니다.
| 주소 | 결과 |
|---|---|
/field-notes/ | 200 |
/field-notes/posts | 200 |
/field-notes/rss.xml | 200 |
/field-notes/robots.txt | 200 |
어떤 주소가 움직이지 않았나?
관리자 화면과 API는 제자리에 남습니다.
| 주소 | 결과 |
|---|---|
/_emdash/api/health | 200 |
/_emdash/admin | 302, /_emdash/admin/setup으로 이동 |
즉 /_emdash로 시작하는 모든 것은 /field-notes 안으로 옮겨 가지 않습니다. 앞단의 라우팅 규칙은 /field-notes/*와 /_emdash/*를 모두 이 애플리케이션으로 보내야 합니다. 앞의 것만 보내면 관리자 화면이 열리지 않습니다.
우리가 마주친 다른 두 주소도 짚어 둘 만합니다. /field-notes/_emdash/api/health와 /field-notes/sitemap.xml은 둘 다 500을 반환합니다. 원래 접근하라고 있는 주소는 아니지만, 점검 스크립트가 “접두사를 붙여서 다시 시도해 본다”는 방식이라면 깜짝 놀라게 됩니다.
또 하나 뜻밖이었던 점은, 루트 경로 /와 /posts도 200을 반환한다는 것입니다. 같은 내용에 입구가 두 개라는 뜻입니다. 검색엔진에 사본 두 개가 보이는 것을 원하지 않는다면, 앞단 라우팅에서 /field-notes/*와 /_emdash/*만 통과시키고 나머지는 모두 거부하세요.
페이지 안의 링크에는 접두사가 하나도 없다
이것이 우리가 가장 예상하지 못한 부분입니다. /field-notes/ 홈페이지를 열고 소스를 보면, 링크는 다음과 같습니다.
- 글 7편:
/posts/a-weekend-with-a-side-project같은 것 - 태그 4개:
/tag/opinion같은 것 - 내비게이션 바:
/,/pages/about,/posts - 그리고
/rss.xml,/search
어느 것에도 /field-notes가 붙어 있지 않습니다. 클릭하면 하위 경로를 벗어나 루트 경로 아래로 떨어집니다.
링크의 출처는 두 곳이며, 고치는 곳이 다릅니다.
- 템플릿 코드에 직접 적혀 있는 것. 예를 들어
src/pages/posts/[slug].astro의href={`/tag/${t.slug}`}, 그리고 여러 페이지에 있는href="/posts"입니다. 이런 것들은import.meta.env.BASE_URL로 시작하도록 바꿔야 합니다. - 데이터베이스에 저장되어 있는 것. 내비게이션의 세 항목은 템플릿에 적혀 있는 것이 아니라 메뉴 데이터로,
_emdash_menu_items테이블에 저장되어 있고 주소는/,/pages/about,/posts입니다. 템플릿만 고치면 내비게이션 바는 꿈쩍도 하지 않습니다. 메뉴 항목 자체의 주소를 바꾸거나, 시드 파일을 바꾼 뒤 다시 넣어야 합니다.
이 템플릿 사이트에서의 이런 작성 방식은 템플릿 자체의 선택이며, base 설정에 문제가 있는 것이 아닙니다. 또한 템플릿 전체를 고친 뒤 검증해 본 것도 아니므로, 여기서는 어디를 찾아야 하는지만 알려 드릴 수 있습니다. 고치면 모두 맞아진다고 보장하지는 못합니다.
기계가 읽는 주소에도 접두사가 없다
사람이 보는 링크 외에 기계가 읽는 것이 세 가지 있어서, 그것도 살펴보았습니다.
/sitemap.xml에 나열된 주소는.../sitemap-posts.xml같은 형태이고, 그 안의 글 주소는.../posts/the-case-for-static같은 형태입니다. 어느 것에도/field-notes가 없습니다.- RSS에서 각 글의
<link>도 마찬가지로.../posts/...입니다. - 루트의
/robots.txt에는Disallow: /_emdash/가 있고 사이트맵도 가리키고 있습니다. 반면/field-notes/robots.txt에는User-agent: *와Allow: /만 있어서,/_emdash/를 막는 규칙도 사이트맵도 없습니다.
마지막 항목은 조금 더 생각해 볼 만합니다. 검색엔진이 robots.txt를 읽으러 가는 곳은 도메인의 루트뿐입니다. 하위 경로 아래에 둔 것은 사실상 아무도 읽지 않습니다. 메인 사이트가 EmDash가 아니라면, 메인 사이트의 robots.txt에서 /_emdash/를 직접 막아야 합니다.
사이트맵과 RSS에 접두사가 없다는 것은, 검색엔진에 제출하는 주소가 하위 경로 바깥의 주소가 된다는 뜻입니다. 이 점은 현상만 확인했고, 어느 코드의 어느 줄이 정하는지는 추적하지 않았습니다.
개발 모드는 사람을 속인다
처음에는 astro dev로 테스트했고, 결과는 이랬습니다.
/_emdash/api/health가 500을 반환했고, 로그에는Cannot read properties of undefined (reading 'registry')가 찍혔습니다./sitemap.xml이 500을 반환했고, 내용은EmDash not configured였습니다.
우리는 base가 런타임을 망가뜨렸다고 생각했습니다. base를 지우자 두 주소가 다시 200으로 돌아와서 더욱 확신했습니다.
그러다 먼저 astro build를 하고 node ./dist/server/entry.mjs로 시작하는 방식으로 바꾸었더니, base를 설정한 상태에서도 위의 두 주소는 모두 200이었습니다.
그러니 하위 경로 설정이 맞는지를 개발 모드로 판단하지 마세요. 두 모드의 차이가 왜 생기는지는 밝혀내지 못했습니다.
서비스 시작 전에 우리가 직접 눌러 볼 곳
- 빌드하고 시작한 뒤, curl로
/field-notes/홈페이지의 소스를 봅니다.href="/로 시작하면서/field-notes가 없는 링크가 있는지 찾아봅니다. /_emdash/admin을 열어, 앞단 라우팅 규칙이 애플리케이션으로 보내 주는지 확인합니다.sitemap.xml과rss.xml안의 주소를 한 번 봅니다.- 메인 사이트의
robots.txt에서/_emdash/가 막혀 있는지 확인합니다. /와/posts에 접속해 보고, 그것들이 존재하기를 원하는지 정합니다.
우리가 테스트하지 않은 것
- 앞단 라우팅 규칙을 실제 Cloudflare Worker나 nginx에 올려 보지는 않았습니다. 위에서 말한 “
/field-notes/*와/_emdash/*를 모두 보내야 한다”는 것은 관찰한 동작에서 추론한 것입니다. - Cloudflare 어댑터에서는 시도하지 않았고, Node에서만 시도했습니다.
- 템플릿 전체의 링크를 끝까지 고쳐 보지는 않았습니다.
하위 경로를 쓰지 않아도 된다면, 별도의 서브도메인을 쓰는 편이 이 글의 내용 대부분을 건너뛰게 해 줍니다.