Astro 설치

create astro CLI 명령은 처음부터 새로운 Astro 프로젝트를 시작하는 가장 빠른 방법입니다. 새로운 Astro 프로젝트 설정의 모든 단계를 안내하며 몇 가지 공식 스타터 템플릿 중에서 선택할 수 있도록 합니다.

template 플래그와 함께 CLI 명령을 실행하여 기존 테마 또는 스타터 템플릿을 사용하여 프로젝트를 시작할 수도 있습니다. 블로그, 포트폴리오, 문서 사이트, 랜딩 페이지 등을 위한 테마를 찾아볼 수 있는 테마 및 스타터 쇼케이스를 살펴보세요!

Astro를 수동으로 설치하려면 단계별 수동 설치 가이드를 참조하세요.

사전 준비 사항

Node.js - v18.20.8 또는 v20.3.0, v22.0.0 이상 (v19 및 v21은 지원되지 않습니다.)
텍스트 편집기 - 공식 Astro 확장 프로그램이 포함된 VS Code를 권장합니다.
터미널 - Astro는 CLI (명령줄 인터페이스)를 통해 액세스됩니다.

브라우저 호환성

Astro는 기본적으로 최신 JavaScript를 지원하는 브라우저를 대상으로 하는 Vite로 빌드되었습니다. 전체 참조는 Vite에서 현재 지원되는 브라우저 버전 목록을 확인하세요.

CLI 마법사로 설치

create astro는 컴퓨터 어디에서든 실행할 수 있으므로 시작하기 전에 프로젝트를 위한 새 빈 디렉터리를 만들 필요가 없습니다. 새 프로젝트를 위한 빈 디렉터리가 아직 없는 경우 마법사가 자동으로 디렉터리를 만드는 데 도움을 줍니다.

터미널에서 다음 명령을 실행하여 설치 마법사를 시작합니다.
- npm
- pnpm
- Yarn
터미널 창
# npm으로 새 프로젝트 시작 npm create astro@latest
터미널 창
# pnpm으로 새 프로젝트 시작 pnpm create astro@latest
터미널 창
# yarn으로 새 프로젝트 시작 yarn create astro
모든 것이 잘 진행되면 성공 메시지와 함께 몇 가지 권장되는 다음 단계가 표시됩니다.
이제 프로젝트가 생성되었으므로 새 프로젝트 디렉터리로 cd하여 Astro를 시작할 수 있습니다.
CLI 마법사에서 “Install dependencies?” 단계를 건너뛴 경우 계속하기 전에 의존성을 설치해야 합니다.
- npm
- pnpm
- Yarn
터미널 창
npm install
터미널 창
pnpm install
터미널 창
yarn install
이제 Astro 개발 서버를 시작하고 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!

CLI 설치 플래그

create astro 명령을 추가 플래그와 함께 실행하여 설정 프로세스 (예: 모든 질문에 “yes”로 응답, Houston 애니메이션 건너뛰기) 또는 새 프로젝트 (예: git 설치 여부, 통합 추가)를 사용자 정의할 수 있습니다.

사용 가능한 모든 create astro 명령 플래그를 확인하세요.

통합 추가

create astro 명령에 --add 인수를 전달하여 astro add 명령을 지원하는 공식 통합 또는 커뮤니티 통합을 설치하면서 새 Astro 프로젝트를 시작할 수 있습니다.

터미널에서 astro add 명령을 지원하는 다른 통합으로 대체하여, 다음 명령을 실행합니다.

# React 및 Partytown이 포함된 새 프로젝트를 생성합니다.
npm create astro@latest -- --add react --add partytown

# React 및 Partytown이 포함된 새 프로젝트를 생성합니다.
pnpm create astro@latest --add react --add partytown

# React 및 Partytown이 포함된 새 프로젝트를 생성합니다.
yarn create astro --add react --add partytown

테마 또는 스타터 템플릿 사용

create astro 명령에 --template 인수를 전달하여 공식 예제 또는 GitHub 리포지토리의 main 브랜치를 기반으로 새 Astro 프로젝트를 시작할 수 있습니다.

터미널에서 사용하려는 테마의 공식 Astro 스타터 템플릿 이름 또는 GitHub 사용자 이름과 리포지토리로 대체하여 다음 명령을 실행합니다.

# 공식 예제로 새 프로젝트를 만듭니다.
npm create astro@latest -- --template <example-name>

# GitHub 리포지토리의 main 브랜치를 기반으로 새 프로젝트를 만듭니다.
npm create astro@latest -- --template <github-username>/<github-repo>

# 공식 예제로 새 프로젝트를 만듭니다.
pnpm create astro@latest --template <example-name>

# GitHub 리포지토리의 main 브랜치를 기반으로 새 프로젝트를 만듭니다.
pnpm create astro@latest --template <github-username>/<github-repo>

# 공식 예제로 새 프로젝트를 만듭니다.
yarn create astro --template <example-name>

# GitHub 리포지토리의 main 브랜치를 기반으로 새 프로젝트를 만듭니다.
yarn create astro --template <github-username>/<github-repo>

기본적으로 이 명령은 템플릿 리포지토리의 main 브랜치를 사용합니다. 다른 브랜치 이름을 사용하려면 --template 인수의 일부로 전달하세요. <github-username>/<github-repo>#<branch>

수동 설정

이 가이드에서는 새 Astro 프로젝트를 수동으로 설치하고 구성하는 단계를 안내합니다.

자동 create astro CLI 도구를 사용하지 않으려면 아래 가이드에 따라 직접 프로젝트를 설정할 수 있습니다.

디렉터리를 만듭니다.

프로젝트 이름으로 빈 디렉터리를 만들고 해당 디렉터리로 이동합니다.
터미널 창
```
mkdir my-astro-project
cd my-astro-project
```
새 디렉터리에 프로젝트의 package.json 파일을 만듭니다. 이 파일은 Astro를 포함하여 프로젝트 의존성을 관리하는 데 사용됩니다. 이 파일 형식에 익숙하지 않은 경우 다음 명령을 실행하여 파일을 만듭니다.
- npm
- pnpm
- Yarn
터미널 창
npm init --yes
터미널 창
pnpm init
터미널 창
yarn init --yes
Astro를 설치합니다.

먼저, 프로젝트에 Astro 프로젝트 의존성을 설치합니다.

Astro는 전역이 아닌 로컬에 설치해야 합니다. npm install -g astro, pnpm add -g astro 또는 yarn add global astro를 실행하고 있지 않은지 확인하세요.
- npm
- pnpm
- Yarn
터미널 창
npm install astro
터미널 창
pnpm add astro
터미널 창
yarn add astro
그런 다음 package.json의 자리 표시자 “scripts” 섹션을 다음으로 바꿉니다.
package.json
```
{
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
}
```
이러한 스크립트는 이 가이드의 뒷부분에서 Astro를 시작하고 다양한 명령을 실행하는 데 사용됩니다.

첫 페이지를 만듭니다.

텍스트 편집기에서 src/pages/index.astro에 새 파일을 만듭니다. 이것은 프로젝트의 첫 번째 Astro 페이지가 됩니다.

이 가이드에서는 다음 코드 스니펫 (--- 대시 포함)을 새 파일에 복사하여 붙여넣습니다.

---
// Astro에 오신 것을 환영합니다!
// 이 삼중 대시 코드 펜스 사이의 모든 것은 "컴포넌트 프런트매터"입니다.
// 브라우저에서 절대 실행되지 않습니다.
console.log('이것은 브라우저가 아닌 터미널에서 실행됩니다!');
---
<!-- 아래는 "컴포넌트 템플릿"입니다.
    HTML일 뿐이지만, 훌륭한 템플릿을 만드는 데 도움이 되는 몇 가지 마법이 뿌려져 있습니다. -->
<html>
  <body>
    <h1>Hello, World!</h1>
  </body>
</html>
<style>
  h1 {
    color: orange;
  }
</style>

첫 번째 정적 자산을 만듭니다.

정적 자산을 저장할 public/ 디렉터리를 만들어야 합니다. Astro는 이러한 자산을 최종 빌드에 항상 포함하므로 컴포넌트 템플릿에서 안전하게 참조할 수 있습니다.

텍스트 편집기에서 public/robots.txt에 새 파일을 만듭니다. robots.txt는 Google과 같은 검색 봇에게 사이트 처리 방법을 알리기 위해 대부분의 사이트에서 포함하는 간단한 파일입니다.

이 가이드에서는 다음 코드 스니펫을 새 파일에 복사하여 붙여넣습니다.
public/robots.txt
```
# 예시: 모든 봇이 사이트를 스캔하고 색인하도록 허용합니다.
# 전체 구문: https://developers.google.com/search/docs/advanced/robots/create-robots-txt
User-agent: *
Allow: /
```
astro.config.mjs를 만듭니다.

Astro는 astro.config.mjs를 사용하여 구성됩니다. 이 파일은 Astro를 구성할 필요가 없는 경우 선택 사항이지만 지금 만드는 것이 좋습니다.

프로젝트 루트에 astro.config.mjs를 만들고 아래 코드를 복사하여 붙여넣습니다.
astro.config.mjs
```
import { defineConfig } from "astro/config";

// https://astro.build/config
export default defineConfig({});
```
React, Svelte 등과 같은 UI 프레임워크 컴포넌트를 포함하거나 프로젝트에서 MDX 또는 Partytown과 같은 다른 도구를 사용하려면 여기에서 통합을 수동으로 가져오고 구성합니다.

자세한 내용은 Astro의 API 구성 참조를 확인하세요.
TypeScript 지원을 추가합니다.

TypeScript는 tsconfig.json을 사용하여 구성됩니다. TypeScript 코드를 작성하지 않더라도 이 파일은 Astro 및 VS Code와 같은 도구가 프로젝트를 이해하는 방법을 알 수 있도록 하는 데 중요합니다. 일부 기능 (예: npm 패키지 가져오기)은 tsconfig.json 파일 없이는 편집기에서 완전히 지원되지 않습니다.

TypeScript 코드를 작성하려는 경우 Astro의 strict 또는 strictest 템플릿을 사용하는 것이 좋습니다. astro/tsconfigs/에서 세 가지 템플릿 구성을 확인하고 비교할 수 있습니다.

프로젝트 루트에 tsconfig.json을 만들고 아래 코드를 복사하여 붙여넣습니다. (TypeScript 템플릿으로 base, strict 또는 strictest를 사용할 수 있습니다.)
tsconfig.json
```
{
  "extends": "astro/tsconfigs/base"
}
```
자세한 내용은 Astro의 TypeScript 설정 가이드를 참조하세요.
다음 단계

위의 단계를 따랐으면 프로젝트 디렉터리가 다음과 같이 표시됩니다.
- 디렉터리node_modules/
  - …
- 디렉터리public/
  - robots.txt
- 디렉터리src/
  - 디렉터리pages/
    index.astro
- astro.config.mjs
- package-lock.json 또는 yarn.lock, pnpm-lock.yaml 등
- package.json
- tsconfig.json
이제 Astro 개발 서버를 시작하고 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!

기여하기 커뮤니티 후원하기