From efa2bf9f51bb62f2600629337feb76f49d94d29a Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:00:49 +0900 Subject: [PATCH 1/9] update `endpoints.mdx` --- src/content/docs/ko/guides/endpoints.mdx | 28 +++++++++++++++--------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/src/content/docs/ko/guides/endpoints.mdx b/src/content/docs/ko/guides/endpoints.mdx index 536f9affcbae1..5f43487b460fa 100644 --- a/src/content/docs/ko/guides/endpoints.mdx +++ b/src/content/docs/ko/guides/endpoints.mdx @@ -59,7 +59,7 @@ import type { APIRoute } from "astro"; const usernames = ["Sarah", "Chris", "Yan", "Elian"]; export const GET = (({ params, request }) => { - const id = params.id; + const id = Number(params.id); return new Response( JSON.stringify({ @@ -113,9 +113,10 @@ export const GET = (({ params, request }) => { 서버 엔드포인트는 `getStaticPaths`를 내보내지 않고도 `params`에 액세스할 수 있으며, 상태 코드 및 헤더를 설정할 수 있는 `Response` 객체를 반환할 수 있습니다. ```js title="src/pages/[id].json.js" +import type { APIRoute } from "astro"; import { getProduct } from "../db"; -export async function GET({ params }) { +export const GET = (async ({ params }) => { const id = params.id; const product = await getProduct(id); @@ -132,7 +133,7 @@ export async function GET({ params }) { "Content-Type": "application/json", }, }); -} +}) satisfies APIRoute; ``` 이렇게 하면 동적 라우트와 일치하는 모든 요청에 응답합니다. 예를 들어 `/helmet.json`으로 이동하면 `params.id`는 `helmet`으로 설정됩니다. `helmet`이 모의 제품 데이터베이스에 존재하면 엔드포인트는 `Response` 객체를 사용하여 JSON으로 응답하고 성공적인 [HTTP 상태 코드](https://developer.mozilla.org/en-US/docs/Web/API/Response/status)를 반환합니다. 그렇지 않으면 `Response` 객체를 사용하여 `404`로 응답합니다. @@ -140,16 +141,18 @@ export async function GET({ params }) { SSR 모드에서는 특정 공급자가 이미지를 반환하기 위해 `Content-Type` 헤더를 요구합니다. 이 경우 `Response` 객체를 사용하여 `headers` 속성을 지정합니다. 예를 들어 바이너리 `.png` 이미지를 생성하려면 다음을 수행합니다. ```ts title="src/pages/astro-logo.png.ts" -export async function GET({ params, request }) { +import type { APIRoute } from "astro"; + +export const GET = (async ({ params, request }) => { const response = await fetch( "https://docs.astro.build/assets/full-logo-light.png", ); - const buffer = Buffer.from(await response.arrayBuffer()); - + const buffer = Buffer.from(await response.arrayBuffer()); // 타입 안전성을 위해 의존성에 `@types/node`가 필요합니다. + return new Response(buffer, { headers: { "Content-Type": "image/png" }, }); -} +}) satisfies APIRoute; ``` ### HTTP 메서드 @@ -159,6 +162,8 @@ export async function GET({ params, request }) { 해당하는 내보낸 함수가 없는 모든 메서드와 일치하도록 `ALL` 함수를 내보낼 수도 있습니다. 일치하는 메서드가 없는 요청이 있으면 사이트의 [404 페이지](/ko/basics/astro-pages/#사용자-정의-404-오류-페이지)로 리디렉션됩니다. ```ts title="src/pages/methods.json.ts" +import type { APIRoute } from "astro"; + export const GET = (({ params, request }) => { return new Response( JSON.stringify({ @@ -201,6 +206,8 @@ export const ALL = (({ request }) => { SSR 모드에서 `request` 속성은 현재 요청을 참조하는 완전히 사용 가능한 [`Request`](https://developer.mozilla.org/ko/docs/Web/API/Request) 객체를 반환합니다. 이를 통해 데이터를 수락하고 헤더를 확인할 수 있습니다. ```ts title="src/pages/test-post.json.ts" +import type { APIRoute } from "astro"; + export const POST = (async ({ request }) => { if (request.headers.get("Content-Type") === "application/json") { const body = await request.json(); @@ -224,10 +231,11 @@ export const POST = (async ({ request }) => { 엔드포인트 컨텍스트는 `Astro.redirect`와 유사한 `redirect()` 유틸리티를 내보냅니다. -```js title="src/pages/links/[id].js" {14} +```js title="src/pages/links/[id].js" {15} +import type { APIRoute } from "astro"; import { getLinkUrl } from "../db"; -export async function GET({ params, redirect }) { +export const GET = (async ({ params, redirect }) => { const { id } = params; const link = await getLinkUrl(id); @@ -239,5 +247,5 @@ export async function GET({ params, redirect }) { } return redirect(link, 307); -} +}) satisfies APIRoute; ``` From 132a79fbd2332965b8c8a6825d154006b5e90b49 Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:07:29 +0900 Subject: [PATCH 2/9] cloudflare --- src/content/docs/ko/guides/integrations-guide/cloudflare.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ko/guides/integrations-guide/cloudflare.mdx b/src/content/docs/ko/guides/integrations-guide/cloudflare.mdx index fd5b4074b44c1..e1e37c81d1bb8 100644 --- a/src/content/docs/ko/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/ko/guides/integrations-guide/cloudflare.mdx @@ -125,8 +125,9 @@ Cloudflare 어댑터는 [`@cloudflare/vite-plugin`](https://developers.cloudflar - **`cloudflare`:** [Cloudflare Image Resizing](https://developers.cloudflare.com/images/image-resizing/) 서비스를 사용합니다. - **`cloudflare-binding`:** 이미지 변환을 위해 [Cloudflare Images 바인딩](https://developers.cloudflare.com/images/transform-images/bindings/)을 사용합니다. 바인딩은 배포 시 자동으로 프로비저닝됩니다. - **`passthrough`:** 기존 [`noop`](/ko/guides/images/#무작동-패스스루-서비스-구성) 서비스를 사용합니다. -- **`compile`:** 사전 렌더링된 경로에 대해 빌드 시 로컬에서 이미지를 변환하기 위해 내부 의존성 조합을 사용합니다. 주문형 렌더링 페이지에는 noop `passthrough` 옵션이 구성됩니다. -- **`custom`:** 항상 [이미지 옵션](/ko/reference/configuration-reference/#이미지-옵션)에 구성된 이미지 서비스를 사용합니다. **이 옵션은 구성된 이미지 서비스가 Cloudflare의 `workerd` 런타임에서 작동하는지 확인하지 않습니다.** +- **`compile`:** [구성된 이미지 서비스](/ko/reference/configuration-reference/#imageservice)를 사용하거나, 이미지 서비스가 구성되지 않은 경우 내부 의존성을 조합하여 사전 렌더링 경로의 이미지를 빌드 시점에 로컬에서 변환합니다. 주문형 렌더링 페이지에서는 아무 작업도 수행하지 않는 `passthrough` 옵션이 사용됩니다. +- **`custom`:** [구성된 이미지 서비스](/ko/reference/configuration-reference/#imageservice)(기본값: Sharp)를 사용하여 사전 렌더링 경로의 에셋을 빌드 시점에 처리합니다. 또한 런타임 이미지 처리를 위해 이미지 서비스를 번들에 포함하지만, 해당 서비스가 Cloudflare의 `workerd` 런타임과 호환되는지는 검사하지 않습니다. + 이미지 서비스를 객체로 구성하여 빌드 시점 서비스와 런타임 서비스를 각각 독립적으로 설정할 수도 있습니다. 현재 빌드 시점 옵션으로는 `'compile'`만 사용할 수 있습니다. 지원되는 런타임 옵션은 `'passthrough'` (기본값) 및 `'cloudflare-binding'`입니다. From 75593f7b775c182bc108750d6db06f6d6cc827b0 Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:12:33 +0900 Subject: [PATCH 3/9] netlify --- .../ko/guides/integrations-guide/netlify.mdx | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ko/guides/integrations-guide/netlify.mdx b/src/content/docs/ko/guides/integrations-guide/netlify.mdx index bc45db64da837..097570aa28464 100644 --- a/src/content/docs/ko/guides/integrations-guide/netlify.mdx +++ b/src/content/docs/ko/guides/integrations-guide/netlify.mdx @@ -352,6 +352,7 @@ export default defineConfig({ - 로컬 [Netlify Blobs](https://docs.netlify.com/build/data-and-storage/netlify-blobs/) 서버. 기본적으로 [세션](#세션)에 사용됩니다. - Netlify 구성의 [리디렉션, URL 재작성 (Rewrites)](https://docs.netlify.com/manage/routing/redirects/overview/) 및 [헤더](https://docs.netlify.com/manage/routing/headers/) - 요청 시 렌더링되는 페이지에서 [Netlify Edge Context](#사이트에서-에지-컨텍스트에-액세스하기)에 액세스 +- 프로젝트의 `netlify/edge-functions` 디렉터리에 정의된 [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/) 에뮬레이션 - Netlify 사이트의 [환경 변수](https://docs.netlify.com/build/environment-variables/overview/) 로컬 사이트가 `netlify link`를 사용하여 [Netlify 사이트에 연결](https://docs.netlify.com/api-and-cli-guides/cli-guides/get-started-with-cli/#link-and-unlink-sites)되어 있을 때 가장 잘 작동합니다. @@ -362,13 +363,13 @@ export default defineConfig({

**타입:** `boolean | object`
-**기본값:** `{ images: true, environmentVariables: false }`
+**기본값:** `{ images: true, environmentVariables: false, edgeFunctions: true }`

`devFeatures` 옵션은 모든 기능을 활성화 또는 비활성화하는 부울이거나 특정 기능을 활성화하는 객체일 수 있습니다. -```js title="astro.config.mjs" ins={7-12} +```js title="astro.config.mjs" ins={7-14} import { defineConfig } from 'astro/config'; import netlify from '@astrojs/netlify'; @@ -380,6 +381,8 @@ export default defineConfig({ images: false, // 개발 모드에서 Netlify 환경 변수를 주입합니다. 기본값은 false입니다. environmentVariables: true, + // 개발 모드에서 Netlify Edge Functions를 에뮬레이션합니다. 기본값은 true입니다. + edgeFunctions: false, }, }), }); @@ -409,6 +412,18 @@ Netlify 사이트의 환경 변수를 개발 환경으로 주입합니다. 이를 통해 프로덕션 환경과 동일한 값을 개발 환경에서 사용할 수 있습니다. 환경마다 다른 변수를 사용하는 방법을 비롯한 자세한 내용은 [환경 변수에 대한 Netlify 문서](https://docs.netlify.com/build/environment-variables/overview/)를 참조하세요. +##### `devFeatures.edgeFunctions` + +

+**타입:** `boolean`
+**기본값:** `true`
+ +

+ +개발 환경에서 프로젝트의 `netlify/edge-functions` 디렉터리에 정의된 [Netlify Edge Functions](https://docs.netlify.com/build/edge-functions/overview/)을 에뮬레이션합니다. + +초기화 과정에서 파일 시스템에 접근하는 일부 npm 패키지는 에지 함수 샌드박스 환경에서 작동하지 않으며, `Reading or writing files with Edge Functions is not supported yet`와 같은 오류가 발생할 수 있습니다. 이러한 오류가 발생하는 경우 `edgeFunctions`를 `false`로 설정하여 에지 함수 에뮬레이션을 비활성화하고, 대신 `netlify dev`를 사용하세요. 에지 함수는 프로덕션 빌드에서는 계속 정상적으로 동작합니다. + ### `staticHeaders`

From f4a9b74789cfbaca170127603c5acd9990a4d9c2 Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:14:47 +0900 Subject: [PATCH 4/9] i18n --- src/content/docs/ko/guides/internationalization.mdx | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/ko/guides/internationalization.mdx b/src/content/docs/ko/guides/internationalization.mdx index f163371de1479..4d6eecc685547 100644 --- a/src/content/docs/ko/guides/internationalization.mdx +++ b/src/content/docs/ko/guides/internationalization.mdx @@ -193,12 +193,12 @@ Astro는 미들웨어를 위한 도우미 함수를 제공하므로 기본 라 ```js title="src/middleware.js" import { defineMiddleware } from "astro:middleware"; -import { redirectToDefaultLocale } from "astro:i18n"; // 'manual' 라우팅으로 사용 가능한 함수 -export const onRequest = defineMiddleware(async (ctx, next) => { - if (ctx.url.startsWith("/about")) { +import { redirectToDefaultLocale } from "astro:i18n"; // `manual` 라우팅에서 사용할 수 있는 함수 +export const onRequest = defineMiddleware((ctx, next) => { + if (ctx.url.pathname.startsWith("/about")) { return next(); } else { - return redirectToDefaultLocale(302); + return redirectToDefaultLocale(ctx, 302); } }) ``` From 086107f58320ba5808a36ed47fc275c9a94decb4 Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:15:27 +0900 Subject: [PATCH 5/9] middleware --- src/content/docs/ko/guides/middleware.mdx | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/content/docs/ko/guides/middleware.mdx b/src/content/docs/ko/guides/middleware.mdx index f30eac91f7147..861d6c57a8dfd 100644 --- a/src/content/docs/ko/guides/middleware.mdx +++ b/src/content/docs/ko/guides/middleware.mdx @@ -257,6 +257,8 @@ export function onRequest (context, next) { 이 시그니처로 `next()`를 호출하면 이전 `ctx.request`를 사용하여 새 `Request` 객체가 생성됩니다. 즉, 이 리라이트 전이나 후에 `Request.body`를 사용하려고 하면 런타임 오류가 발생합니다. 이 오류는 [HTML 양식을 사용하는 Astro 액션](/ko/guides/actions/#html-양식-액션에서-액션-호출)에서 자주 발생합니다. 이러한 경우 미들웨어를 대신 `Astro.rewrite()`를 사용하여 Astro 템플릿에서 리라이트를 처리하는 것이 좋습니다. ```js title="src/middleware.js" +import { sequence } from "astro:middleware"; + // 현재 URL은 https://example.com/blog // 첫 미들웨어 함수 From db48dc6cc65d0feadc869a6caba1d0fc73797c15 Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:16:21 +0900 Subject: [PATCH 6/9] prefetch --- src/content/docs/ko/guides/prefetch.mdx | 12 +++++++----- 1 file changed, 7 insertions(+), 5 deletions(-) diff --git a/src/content/docs/ko/guides/prefetch.mdx b/src/content/docs/ko/guides/prefetch.mdx index 5e668a10ba8d0..872d6a28f8c2e 100644 --- a/src/content/docs/ko/guides/prefetch.mdx +++ b/src/content/docs/ko/guides/prefetch.mdx @@ -100,7 +100,7 @@ export default defineConfig({ import { prefetch } from 'astro:prefetch'; const btn = document.getElementById('btn'); - btn.addEventListener('click', () => { + btn?.addEventListener('click', () => { prefetch('/about'); }); @@ -158,11 +158,13 @@ prefetch('/terms-of-service', { eagerness: 'moderate' }); 멋진 링크 20 ``` From 3f7ab7e0d1e71d2c1a5b9a4544f213b48a57d271 Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:17:25 +0900 Subject: [PATCH 7/9] typescript --- src/content/docs/ko/guides/typescript.mdx | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/content/docs/ko/guides/typescript.mdx b/src/content/docs/ko/guides/typescript.mdx index 440f6c8b8806c..6db866ff21a25 100644 --- a/src/content/docs/ko/guides/typescript.mdx +++ b/src/content/docs/ko/guides/typescript.mdx @@ -306,13 +306,14 @@ Astro는 동적 라우트를 위한 [`getStaticPaths()`](/ko/reference/routing-r `InferGetStaticParamsType`으로 [`Astro.params`](/ko/reference/api-reference/#params)의 타입을 얻고, `InferGetStaticPropsType`으로 [`Astro.props`](/ko/reference/api-reference/#props)의 타입을 얻을 수 있습니다. 또는 `GetStaticPaths`를 사용하여 두 타입을 모두 얻을 수 있습니다. -```astro title="src/pages/posts/[...id].astro" {2-6,18-19} "satisfies GetStaticPaths;" +```astro title="src/pages/posts/[...id].astro" {2-6,19-20} "satisfies GetStaticPaths;" --- import type { InferGetStaticParamsType, InferGetStaticPropsType, GetStaticPaths, } from "astro"; +import { getCollection } from "astro:content"; export const getStaticPaths = (async () => { const posts = await getCollection("blog"); @@ -327,7 +328,7 @@ export const getStaticPaths = (async () => { type Params = InferGetStaticParamsType; type Props = InferGetStaticPropsType; -const { id } = Astro.params as Params; +const { id } = Astro.params; // ^? { id: string; } const { title } = Astro.props; From 10d3f10c024a6a156d78c3fc79a01642388f2a7a Mon Sep 17 00:00:00 2001 From: Junseong Park <39112954+jsparkdev@users.noreply.github.com> Date: Thu, 2 Jul 2026 12:23:42 +0900 Subject: [PATCH 8/9] routing --- src/content/docs/ko/guides/routing.mdx | 46 ++++++++++++++++---------- 1 file changed, 29 insertions(+), 17 deletions(-) diff --git a/src/content/docs/ko/guides/routing.mdx b/src/content/docs/ko/guides/routing.mdx index 93b960bf3f6f6..bfa5fad68bf63 100644 --- a/src/content/docs/ko/guides/routing.mdx +++ b/src/content/docs/ko/guides/routing.mdx @@ -431,23 +431,26 @@ Astro는 여러 페이지로 분할해야 하는 대규모 데이터 컬렉션 다음과 같이 `paginate()` 함수를 사용하여 값 배열에 대한 이러한 페이지를 생성할 수 있습니다. -```astro /{ (paginate) }/ /paginate\\(.*\\);/ /(?<=const.*)(page)/ /page\\.[a-zA-Z]+/ +```astro title="src/pages/astronauts/[page].astro" /{ (paginate) }/ /paginate\\(.*\\);/ /(?<=const.*)(page)/ /page\\.[a-zA-Z]+/ --- -// src/pages/astronauts/[page].astro -export function getStaticPaths({ paginate }) { +import type { GetStaticPaths } from "astro"; + +export const getStaticPaths = (({ paginate }) => { const astronautPages = [ { astronaut: "Neil Armstrong" }, { astronaut: "Buzz Aldrin" }, { astronaut: "Sally Ride" }, { astronaut: "John Glenn" }, ]; - - // astronauts 배열로부터 페이지를 생성하며, 각 페이지에는 2개의 항목이 표시됩니다. + + // 우주비행사 배열을 기반으로, 페이지당 2개의 항목을 포함하는 페이지를 생성합니다. return paginate(astronautPages, { pageSize: 2 }); -} -// 페이지네이션된 모든 데이터는 "page" prop으로 전달됩니다. +}) satisfies GetStaticPaths; + +// 모든 페이지네이션 데이터는 `page` prop을 통해 전달됩니다. const { page } = Astro.props; --- +

Page {page.currentPage}