Astro 설치 및 설정

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

또는 기존 테마나 시작 템플릿을 사용하여 프로젝트를 시작할 수도 있습니다.

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

전제 조건

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

새 프로젝트 시작

CLI 마법사로 설치

편리한 설치 마법사를 시작하려면 터미널에서 다음 명령을 실행하세요.
- npm
- pnpm
- yarn
Terminal window
# npm으로 새 프로젝트 만들기 npm create astro@latest
Terminal window
# pnpm으로 새 프로젝트 만들기 pnpm create astro@latest
Terminal window
# yarn으로 새 프로젝트 만들기 yarn create astro
컴퓨터의 어느 곳에서나 create astro를 실행할 수 있으므로 시작하기 전에 프로젝트를 위한 새로운 빈 디렉터리를 만들 필요가 없습니다. 새 프로젝트를 위한 빈 디렉터리가 아직 없다면 마법사가 자동으로 디렉터리를 만드는 데 도움을 줍니다.

모든 것이 순조롭게 진행되면 성공 메시지와 함께 권장되는 다음 단계가 표시됩니다. 이제 프로젝트가 생성되었으므로 새 프로젝트 디렉터리에 cd하여 Astro를 시작할 수 있습니다.
CLI 마법사를 실행하는 중 npm install 단계를 건너뛴 경우 계속 진행하기 전에 종속성을 설치해야 합니다.
이제 Astro 개발 서버를 시작하여 빌드하는 동안 프로젝트의 실시간 미리보기를 볼 수 있습니다!

테마 또는 시작 템플릿 사용

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

블로그, 포트폴리오, 문서 사이트, 랜딩 페이지 등 다양한 테마를 찾아볼 수 있는 테마 및 스타터 쇼케이스를 살펴보세요! 또는 더 많은 시작 프로젝트를 찾기 위해 GitHub에서 검색하세요.

공식 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>를 전달하세요.

질문에 답하여 CLI 마법사의 지시를 따릅니다.
이제 Astro 개발 서버를 시작하여 프로젝트를 직접 만드는 동안 실시간 미리보기를 볼 수 있습니다!

프로젝트 편집

프로젝트를 변경하려면 코드 편집기에서 프로젝트 폴더를 엽니다. 개발 서버가 실행 중인 상태에서 개발 모드로 작업하면 코드를 편집하면서 사이트 업데이트를 확인할 수 있습니다.

TypeScript 구성이나 공식 Astro 편집기 확장 설치 등 개발 환경 측면을 사용자 정의할 수도 있습니다.

Astro 개발 서버 시작

Astro에는 프로젝트 개발에 필요한 모든 것을 갖춘 개발 서버가 내장되어 있습니다. astro dev CLI 명령은 로컬 개발 서버를 시작하여 처음으로 새 웹사이트가 작동하는 모습을 볼 수 있습니다.

모든 시작 템플릿에는 astro dev를 실행할 사전 구성된 스크립트가 함께 제공됩니다. 프로젝트 디렉터리로 이동한 후 선호하는 패키지 관리자를 통해 이 명령을 실행하여 Astro 개발 서버를 시작하세요.

npm run dev

pnpm run dev

yarn run dev

모든 것이 순조롭게 진행되었다면 Astro는 이제 http://localhost:4321/에서 프로젝트를 서비스하게 될 것입니다. 브라우저에서 해당 링크를 방문하여 새 사이트를 확인하세요!

개발 모드에서 작업

Astro는 src/ 디렉터리에서 실시간 파일 변경 사항을 수신하고 빌드할 때 사이트 미리보기를 업데이트하므로 개발 중 변경 사항을 적용할 때 서버를 다시 시작할 필요가 없습니다. 개발 서버가 실행 중일 때 항상 브라우저에서 사이트의 최신 버전을 볼 수 있습니다.

브라우저에서 사이트를 보면 Astro 개발 툴바에 액세스할 수 있습니다. 빌드하면서 아일랜드를 검사하고 접근성 문제 등을 발견하는 데 도움이 됩니다.

개발 서버를 시작한 후 브라우저에서 프로젝트를 열 수 없는 경우 dev 명령을 실행한 터미널로 돌아가서 표시된 메시지를 확인하세요. 오류가 발생했는지 또는 프로젝트가 http://localhost:4321/이 아닌 다른 URL에서 제공되는지 알려줍니다.

개발 환경 구성

아래 가이드를 살펴보고 개발 환경을 맞춤설정하세요.

편집기 설정 Astro의 개발자 경험을 개선하고 새로운 기능을 잠금 해제하려면 코드 편집기를 사용자 정의하세요.

개발 툴바 개발 툴바의 유용한 기능을 살펴보세요.

Astro에서 TypeScript 사용

Astro에는 코드에서 객체 및 컴포넌트의 모양을 정의하여 런타임 오류를 방지하는 데 도움이 되는 TypeScript 지원이 내장되어 있습니다.

이점을 누리기 위해 Astro 프로젝트에서 TypeScript 코드를 작성할 필요는 없습니다. Astro는 항상 컴포넌트 코드를 TypeScript로 처리하며 Astro VSCode 확장은 편집기에서 자동 완성, 힌트 및 오류를 제공하기 위해 최대한 많이 추론합니다.

Astro에서 TypeScript 사용 및 구성에 대해 자세히 알아보세요.

사이트 빌드 및 미리보기

빌드 시 생성될 사이트 버전을 확인하려면 개발 서버를 종료하고 (Ctrl + C) 터미널에서 패키지 관리자에 적합한 빌드 명령을 실행하세요.

npm run build

pnpm build

yarn run build

Astro는 배포 가능한 버전의 사이트를 별도의 폴더 (기본적으로 dist/)에 빌드하고 터미널에 진행 상황을 표시합니다. 이렇게 하면 프로덕션에 배포하기 전에 프로젝트의 빌드 오류를 확인할 수 있습니다. TypeScript가 strict 또는 strictest로 구성된 경우 build 스크립트는 프로젝트의 타입 오류도 확인합니다.

빌드가 완료되면 터미널에서 적절한 preview 명령 (예: npm run preview)을 실행하세요. 동일한 브라우저 미리보기 창에서 로컬로 사이트의 빌드된 버전을 볼 수 있습니다.

이렇게 하면 빌드 명령이 마지막으로 실행되었을 때 존재했던 코드를 미리 볼 수 있습니다. 이는 사이트가 웹에 배포되었을 때 어떻게 보일지 미리 보여주기 위한 것입니다. 빌드 후 코드를 변경하더라도 빌드 명령을 다시 실행하기 전까지 사이트의 미리 보기에는 해당 변경 사항이 반영되지 않습니다.

(Ctrl + C)를 사용하여 미리보기를 종료하고 다른 터미널 명령을 실행하세요. 예를 들어 코드 변경 사항을 실시간으로 확인하기 위해 개발 서버를 다시 시작하여 편집할 때 업데이트되는 개발 모드 작업으로 돌아갑니다.

Astro CLI 및 Astro로 빌드할 때 사용할 터미널 명령에 대해 자세히 알아보세요.

새 사이트 배포

너무 많은 코드를 추가하거나 변경하기 전에 새 사이트를 즉시 배포하는 것이 좋습니다. 이는 사이트의 최소한의 작동 버전을 게시하는 데 도움이 되며 나중에 배포 문제를 해결하는 데 투입되는 시간과 노력을 절약할 수 있습니다.

다음 단계

성공! 이제 Astro로 빌드를 시작할 준비가 되었습니다! 🥳

앞으로 살펴보실 것을 권장하는 몇 가지 사항은 다음과 같습니다. 어떤 순서로든 읽을 수 있습니다. 문서를 잠시 남겨두고 새 Astro 프로젝트 코드베이스를 사용해 보고 문제가 발생하거나 질문이 있을 때마다 여기로 돌아올 수도 있습니다.

Astro의 기능 살펴보기

코드베이스 이해 프로젝트 구조 가이드에서 Astro의 파일 구조에 대해 알아보세요.

콘텐츠 컬렉션 생성 새 사이트에 프런트매터 검증 및 타입 안전성을 갖춘 콘텐츠를 추가하세요.

view transitions 추가 원활한 페이지 전환과 애니메이션을 만드세요.

아일랜드에 대해 알아보기 Astro의 아일랜드 아키텍쳐에 대해 알아보세요.

입문용 튜토리얼

입문용 튜토리얼을 통해 하나의 빈 페이지에서 시작하여 완전한 기능을 갖춘 Astro 블로그를 구축하세요.

이는 Astro의 작동 방식 및 페이지, 레이아웃, 컴포넌트, 라우팅, 아일랜드 등 기본 사항을 직접 살펴볼 수 있는 좋은 방법입니다. 또한 일반적으로 웹 개발 개념을 처음 접하는 사람들을 위한 선택적이고 초보자 친화적인 유닛도 포함되어 있습니다. 이 유닛은 컴퓨터에 필수 응용 프로그램을 설치하고, GitHub 계정을 만들고, 사이트를 배포하는 과정을 안내합니다.

수동 설정

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

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

디렉터리 만들기

프로젝트 이름으로 빈 디렉터리를 만든 다음 해당 디렉터리로 이동합니다.
Terminal window
```
mkdir my-astro-project
cd my-astro-project
```
새 디렉터리에 있으면 프로젝트 package.json 파일을 만듭니다. 이것이 Astro를 포함한 프로젝트 종속성을 관리하는 방법입니다. 이 파일 형식에 익숙하지 않은 경우 다음 명령을 실행하여 파일 형식을 만드세요.
- npm
- pnpm
- yarn
Terminal window
npm init --yes
Terminal window
pnpm init
Terminal window
yarn init --yes
Astro 설치

먼저 프로젝트에 Astro 프로젝트 종속성을 설치하세요.

Astro는 전역이 아닌 로컬에 설치해야 합니다. npm install -g astro pnpm add -g astro 또는 yarn add global astro를 실행하지 않았는지 확인하세요.
- npm
- pnpm
- yarn
Terminal window
npm install astro
Terminal window
pnpm add astro
Terminal window
yarn add astro
그런 다음 package.json의 자리 표시자 “scripts” 섹션을 다음으로 바꿉니다.
package.json
```
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  },
```
이 스크립트는 나중에 Astro를 시작하고 다양한 명령을 실행하기 위해 가이드에서 사용할 것입니다.

첫 번째 페이지 만들기

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

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

---
// Astro에 오신 것을 환영합니다! 삼중 대시 코드 펜스 사이 모든 것이 "컴포넌트 프런트매터"입니다. 브라우저에서는 절대 실행되지 않습니다.
console.log('This runs in your terminal, not the browser!');
---
<!-- 아래는 "컴포넌트 템플릿"입니다. 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 프레임워크 컴포넌트를 포함하거나 Tailwind 또는 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"
}
```
마지막으로 src/env.d.ts를 생성하여 Astro 프로젝트에서 사용할 수 있는 앰비언트 타입을 TypeScript에 알립니다.
src/env.d.ts
```
/// <reference types="astro/client" />
```
자세한 내용은 Astro의 TypeScript 설정 가이드를 확인하세요.
다음 단계

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

GitHub Issue 생성

의견 보내기