문제 해결

Astro는 코드 문제를 해결하고 디버깅하는 데 도움이 되는 다양한 도구를 제공합니다.

팁과 요령

`console.log()`로 디버깅

console.log()는 Astro 코드를 디버깅하는 간단하지만 널리 사용되는 방법입니다. console.log() 문을 작성하는 위치에 따라 디버깅 출력이 인쇄되는 위치가 결정됩니다.

---
console.log('안녕! 나는 서버입니다. 이는 Astro가 실행 중인 터미널에 기록됩니다.');
---

<script>
console.log('안녕! 나는 클라이언트입니다. 이는 브라우저 개발 콘솔에 기록됩니다.');
</script>

Astro 프론트매터의 console.log() 문은 항상 Astro CLI를 실행하는 터미널에 출력됩니다. 이는 Astro가 서버에서 실행되고 브라우저에서는 실행되지 않기 때문입니다.

Astro <script> 태그에 작성되거나 가져온 코드는 브라우저에서 실행됩니다. 모든 console.log() 문이나 기타 디버그 출력은 브라우저의 콘솔에 출력됩니다.

프레임워크 컴포넌트 디버깅

프레임워크 컴포넌트 (예: React 및 Svelte)는 고유합니다. 기본적으로 서버 측에서 렌더링됩니다. 즉 console.log() 디버그 출력이 터미널에 나타납니다. 그러나 브라우저에 대해 수화될 수도 있으며, 이로 인해 디버그 로그가 브라우저에도 나타날 수 있습니다.

이는 서버 출력과 브라우저의 수화된 컴포넌트 간 차이점을 디버깅하는 데 유용할 수 있습니다.

Astro `<Debug />` 컴포넌트

Astro 컴포넌트 디버깅을 돕기 위해 Astro는 모든 값을 컴포넌트 HTML 템플릿에 직접 렌더링하는 내장 <Debug /> 컴포넌트를 제공합니다.

이 컴포넌트는 JavaScript 없이 클라이언트 측에서 값을 검사할 수 있는 방법을 제공합니다. 이는 터미널과 브라우저를 전환하지 않고 브라우저에서 빠르게 디버깅하는 데 유용할 수 있습니다.

---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
---

<!-- 예: 브라우저에 {answer: 6}을 출력합니다. -->
<Debug answer={sum(2, 4)} />

Debug 컴포넌트는 더욱 유연하고 간결한 디버깅을 위해 다양한 구문 옵션을 지원합니다.

---
import { Debug } from 'astro:components';
const sum = (a, b) => a + b;
const answer = sum(2, 4);
---
<!-- 예: 세 가지 예시는 모두 동일합니다. -->
<Debug answer={sum(2, 4)} />
<Debug {{answer: sum(2, 4)}} />
<Debug {answer} />

일반적인 오류 메시지

다음은 터미널에서 볼 수 있는 몇 가지 일반적인 오류 메시지와 그 의미, 해결 방법입니다. 발생할 수 있는 Astro 오류의 전체 목록은 전체 오류 참조 안내서를 참조하세요.

Cannot use import statement outside a module

Astro 컴포넌트에서 <script> 태그는 기본적으로 JS 모듈로 로드됩니다. 태그에 is:inline 지시어 또는 기타 속성을 포함한 경우 이 기본 동작은 제거됩니다.

해결책: <script> 태그에 속성을 추가한 경우 import 문을 사용할 수 있도록 type="module" 속성도 추가해야 합니다.

상태: Astro가 의도한 대로 동작할 것으로 예상됩니다.

이것이 여러분의 문제인지 확실하지 않습니까? 다른 사람이 이 문제를 보고했는지 확인하세요!

`document` (or `window`) is not defined

이 오류는 서버의 document 또는 window에 액세스하려고 할 때 발생합니다.

Astro 컴포넌트는 서버에서 실행되므로 프런트매터에서 이러한 브라우저 전용 객체에 액세스할 수 없습니다.

프레임워크 컴포넌트는 기본적으로 서버에서 실행되므로, 렌더링 중 document 또는 window에 액세스할 때 이 오류가 발생할 수 있습니다.

해결책: document 또는 window를 호출하는 코드를 사용합니다. document 또는 window를 직접 사용하지 않는데도 여전히 이 오류가 발생하는 경우에는 가져오는 패키지가 클라이언트에서 실행되도록 구성되어 있는지 확인하세요.

코드가 Astro 컴포넌트에 있는 경우 이를 프런트매터 외부 <script> 태그로 이동하세요. 이는 Astro가 document와 window를 사용할 수 있는 클라이언트에서 이 코드를 실행하도록 지시합니다.
코드가 프레임워크 컴포넌트에 있는 경우 수명 주기 메서드 (예: React의 useEffect(), Vue의 onMounted(), Svelte의 onMount())를 사용하여 렌더링한 후 이러한 객체에 액세스해 보세요. 이러한 수명 주기 메서드를 실행하려면 client:load와 같은 client: 지시어를 사용하여 클라이언트 측 수화가 실행되도록 프레임워크 컴포넌트에 지시합니다. client:only 지시어를 추가하여 컴포넌트가 서버에서 전혀 렌더링되지 않도록 할 수도 있습니다.

상태: Astro가 의도한 대로 동작할 것으로 예상됩니다.

Expected a default export

이 오류는 유효하지 않은 컴포넌트 또는 제대로 작동하지 않는 컴포넌트를 가져오거나 렌더링하려고 할 때 발생할 수 있습니다. (이 특정 메시지는 Astro에서 UI 컴포넌트 가져오기가 작동하는 방식 때문에 발생합니다.)

해결책: 가져오고 렌더링하는 컴포넌트에서 오류를 찾아보고 올바르게 작동하는지 확인하세요. astro.new에서 Astro 시작 템플릿을 열고 최소한의 Astro 프로젝트에서 컴포넌트 문제를 해결해 보세요.

상태: Astro가 의도한 대로 동작할 것으로 예상됩니다.

Refused to execute inline script

브라우저 콘솔에 다음 오류가 기록될 수 있습니다.

Refused to execute inline script because it violates the following Content Security Policy directive: …

이는 여러분의 사이트의 콘텐츠 보안 정책 (CSP)이 Astro가 출력하는 인라인 <script> 태그 실행을 허용하지 않음을 의미합니다.

해결책: 인라인 스크립트 실행을 허용하려면 script-src: 'unsafe-inline'을 포함하도록 CSP를 업데이트하세요. 또는 astro-shield와 같은 타사 통합을 사용하여 CSP 헤더를 생성할 수 있습니다.

일반적인 문제

내 컴포넌트가 렌더링되지 않습니다.

먼저, .astro 컴포넌트 스크립트 또는 .mdx 파일에서 컴포넌트를 가져왔는지 확인하세요.

그런 다음 가져오기 (import) 문을 확인하세요.

가져오기가 잘못된 위치로 연결되어 있습니까? (가져오기 경로를 확인하세요.)
가져오기가 가져온 컴포넌트와 이름이 동일합니까? (컴포넌트 이름이 .astro 구문을 따르는지 확인하세요).
가져오기에 확장자를 포함시켰나요? (가져온 파일에 확장자가 포함되어 있는지 확인하세요. 예: .astro, .md, .vue, .svelte. 참고: .js(x) 및 .ts(x) 파일에는 확장자가 필요하지 않습니다.)

내 컴포넌트가 대화형이 아닙니다.

컴포넌트가 렌더링 중이지만 (위 참조) 사용자 상호 작용에 응답하지 않는 경우 컴포넌트를 수화하기 위한 client:* 지시어가 누락되었을 수 있습니다.

기본적으로 UI 프레임워크 컴포넌트는 클라이언트에서 수화되지 않습니다. client:* 지시어가 제공되지 않으면 해당 HTML이 JavaScript 없이 페이지에 렌더링됩니다.

패키지 ‘X’를 찾을 수 없습니다

Astro를 시작할 때 "Cannot find package 'react'" (또는 이와 유사한) 경고가 표시되면 해당 패키지를 프로젝트에 설치해야 한다는 의미입니다. 모든 패키지 관리자가 자동으로 피어 종속성을 설치하는 것은 아닙니다. Node v16+를 사용하고 npm을 사용하는 경우 이 섹션에 대해 걱정할 필요가 없습니다.

예를 들어 React는 @astrojs/react 통합의 피어 종속성입니다. 이는 통합과 함께 공식 react 및 react-dom 패키지를 설치해야 함을 의미합니다. 그러면 통합이 이러한 패키지에서 자동으로 가져옵니다.

# 예: 통합과 프레임워크를 함께 설치
npm install @astrojs/react react react-dom

프레임워크 렌더러, CSS 도구 및 기타 패키지를 Astro에 추가하는 방법에 대한 지침은 Astro 통합 가이드를 참조하세요.

Astro를 Yarn 2+ (Berry)와 함께 사용하기

Yarn 2+, 일명 Berry는 Plug’n’Play (PnP)라는 기술을 사용하여 Node 모듈을 저장하고 관리하는데, 이는 create astro를 사용하여 새 Astro 프로젝트를 초기화하거나 Astro로 작업하는 동안 문제를 일으킬 수 있습니다. 해결 방법은 .yarnrc.yml의 nodeLinker 속성을 node-modules로 설정하는 것입니다.

nodeLinker: "node-modules"

모노레포에서 Astro에 종속성 추가

모노레포 설정에서 Astro로 작업할 때 각 프로젝트의 자체 package.json 파일에 프로젝트 종속성을 추가해야 합니다.

그러나 모노레포의 루트에서 Astro를 사용하고 싶을 수도 있습니다 (예: Nx 프로젝트에서는 루트에 종속성 설치를 권장합니다). 이 경우 Astro 관련 종속성 (예: @astrojs/vue, astro-component-lib)을 Astro 구성의 vite.ssr.noExternal 부분에 수동으로 추가하여 이러한 종속성이 올바르게 설치되고 번들링되었는지 확인하세요.

import { defineConfig } from 'astro/config'
export default defineConfig({
  vite: {
    ssr: {
      noExternal: [
        '@astrojs/vue',
        'astro-component-lib',
      ]
    }
  }
})

컴포넌트에서 `<head>` 사용하기

Astro에서 <head> 태그를 사용하는 것은 다른 HTML 태그처럼 작동합니다. 페이지 상단으로 이동하거나 기존 <head>와 병합되지 않습니다. 이 때문에 일반적으로 페이지 전체에 하나의 <head> 태그만 포함하려고 합니다. 단일 <head>와 해당 콘텐츠를 레이아웃 컴포넌트에 작성하는 것이 좋습니다.

예상치 못한 `<style>`이 포함되었습니다.

해당 컴포넌트가 최종 출력에 표시되지 않더라도 가져온 컴포넌트의 <style> 태그가 HTML 소스에 포함되어 있음을 확인할 수 있습니다. 예를 들어, 이는 표시되지 않는 조건부 렌더링 컴포넌트에서 발생합니다.

Astro의 빌드 프로세스는 모듈 그래프에서 작동합니다. 컴포넌트가 템플릿에 포함되면 해당 <style> 태그가 최종 출력에 표시되는지 여부에 관계없이 처리, 최적화 및 번들링됩니다.

Markdown에서 특수 문자 이스케이프

특정 문자는 Markdown에서 특별한 의미를 가집니다. 이러한 문자를 표시하려면 다른 구문을 사용해야 할 수 있습니다. 이를 위해 이러한 문자에 HTML 엔티티를 대신 사용할 수 있습니다.

예를 들어 <가 HTML 요소의 시작 부분으로 해석되는 것을 방지하려면 <를 작성합니다.

최소한의 복제물 만들기

코드 문제를 해결할 때 공유할 수 있는 문제를 최소 재현하는 것이 도움이 될 수 있습니다. 이것은 문제를 보여주는 더 작고 단순화된 Astro 프로젝트입니다. 새 프로젝트에서 작업 재현을 수행하면 이것이 반복 가능한 문제이며 개인 환경이나 기존 프로젝트의 다른 요인으로 인해 발생하는 것이 아니라는 것을 확인하는 데 도움이 됩니다.

최소한의 복제물을 공유하는 것은 지원 스레드에서 도움을 요청할 때 도움이 되며 Astro에 버그 보고서를 제출할 때 종종 필요합니다.

astro.new를 통해 StackBlitz 만들기

astro.new를 사용하면 클릭 한 번으로 새로운 Astro 프로젝트를 만들 수 있습니다. 최소한의 재현을 위해서는 추가 코드를 최대한 적게 사용하여 StackBlitz에서 실행되는 최소 (빈) 예시부터 시작하는 것이 좋습니다.

StackBlitz는 로컬 환경 외부의 브라우저에서 Astro 프로젝트를 실행합니다. 또한 Astro 메인테이너 또는 지원팀 구성원이 자신의 로컬 환경 외부에서 최소한의 복제물을 볼 수 있도록 공유 가능한 링크를 제공합니다. 이는 모든 사람이 동일한 구성과 종속성을 지닌 동일한 프로젝트를 보고 있음을 의미합니다. 이렇게 하면 다른 사람이 여러분의 코드 문제를 쉽게 해결할 수 있습니다. 문제가 재현 가능한 경우 Astro 코드 자체에 문제가 있는지 확인할 수 있으며 자신감을 갖고 버그 보고서를 제출할 수 있습니다.

StackBlitz에서 모든 문제가 재현 가능한 것은 아닙니다. 예를 들어 문제는 특정 환경이나 패키지 관리자에 따라 달라질 수 있거나 StackBlitz에서 지원되지 않는 HTML 스트리밍과 관련될 수 있습니다. 이 경우 CLI를 사용하여 새로운 최소 (빈) Astro 프로젝트를 생성하고 문제를 재현한 후 GitHub 저장소에 업로드하세요. StackBlitz URL을 공유하는 대신 최소 재구현을 위한 GitHub 저장소에 대한 링크를 제공하세요.

최소 코드

빈 프로젝트가 설정되면 문제를 재현하는 단계를 진행하세요. 여기에는 패키지 추가, 구성 변경, 코드 작성이 포함될 수 있습니다.

문제를 재현하는 데 필요한 최소한의 코드만 추가해야 합니다. 기존 프로젝트의 다른 요소를 재현하지 말고, 문제와 직접적인 관련이 없는 모든 코드를 제거하세요.

이슈 생성

이슈를 재현할 수 있다면 이제 이슈를 생성하고 버그 보고서를 제출할 차례입니다!

GitHub의 적절한 Astro 저장소로 이동하여 새 이슈를 엽니다. 대부분의 저장소에는 제출을 위해 질문을 하거나 정보를 요구하는 이슈 템플릿이 있습니다. 우리가 필요한 정보를 제공하지 않으면 우리는 이를 요청해야 하고 아무도 귀하의 문제를 해결하기 위해 노력하지 않기 때문에 이러한 템플릿을 따르는 것이 중요합니다!

StackBlitz (또는 필요한 경우 GitHub 저장소)의 최소 복제물에 대한 링크를 포함하세요. 문제에 대한 맥락을 제공하기 위해 예상되는 동작과 실제 동작에 대한 설명부터 시작하세요. 그런 다음 Astro 프로젝트에서 문제를 재현하는 방법에 대한 명확한 단계별 지침을 포함하세요.

더 필요하신가요?

Discord에 오셔서 채팅하시고 #support 포럼 채널에서 문제를 설명해 주세요. 우리는 언제나 기꺼이 도와드리겠습니다!

현재 Astro에서 열려 있는 이슈를 방문하여 알려진 문제가 있는지 확인하거나 버그 보고서를 제출하세요.

또한 RFC 토론을 방문하여 Astro의 알려진 제한 사항을 발견했는지 확인하고 사용 사례와 관련된 현재 제안이 있는지 확인할 수 있습니다.

기여하기

커뮤니티

문제 해결

팁과 요령

`console.log()`로 디버깅

프레임워크 컴포넌트 디버깅

Astro `<Debug />` 컴포넌트

일반적인 오류 메시지

Cannot use import statement outside a module

`document` (or `window`) is not defined

Expected a default export

Refused to execute inline script

일반적인 문제

내 컴포넌트가 렌더링되지 않습니다.

내 컴포넌트가 대화형이 아닙니다.

패키지 ‘X’를 찾을 수 없습니다

Astro를 Yarn 2+ (Berry)와 함께 사용하기

모노레포에서 Astro에 종속성 추가

컴포넌트에서 `<head>` 사용하기

예상치 못한 `<style>`이 포함되었습니다.

Markdown에서 특수 문자 이스케이프

최소한의 복제물 만들기

astro.new를 통해 StackBlitz 만들기

최소 코드

이슈 생성

더 필요하신가요?

여러분의 생각을 들려주세요!

GitHub Issue 생성

의견 보내기

의견 보내기

문제 해결

팁과 요령

console.log()로 디버깅

프레임워크 컴포넌트 디버깅

Astro <Debug /> 컴포넌트

일반적인 오류 메시지

Cannot use import statement outside a module

document (or window) is not defined

Expected a default export

Refused to execute inline script

일반적인 문제

내 컴포넌트가 렌더링되지 않습니다.

내 컴포넌트가 대화형이 아닙니다.

패키지 ‘X’를 찾을 수 없습니다

Astro를 Yarn 2+ (Berry)와 함께 사용하기

모노레포에서 Astro에 종속성 추가

컴포넌트에서 <head> 사용하기

예상치 못한 <style>이 포함되었습니다.

Markdown에서 특수 문자 이스케이프

최소한의 복제물 만들기

astro.new를 통해 StackBlitz 만들기

최소 코드

이슈 생성

더 필요하신가요?

`console.log()`로 디버깅

Astro `<Debug />` 컴포넌트

`document` (or `window`) is not defined

컴포넌트에서 `<head>` 사용하기

예상치 못한 `<style>`이 포함되었습니다.