컨텐츠로 건너뛰기

CLI 명령

Astro에서 제공하는 명령줄 인터페이스 (CLI)를 사용하여 터미널 창에서 프로젝트를 개발, 빌드, 미리 볼 수 있습니다.

원하는 패키지 관리자로 이 페이지에 설명된 명령 중 하나를 실행하고 선택적으로 플래그를 실행하여 CLI를 사용하세요. 플래그는 명령의 동작을 사용자 정의합니다.

가장 자주 사용하게 될 명령 중 하나는 astro dev입니다. 이 명령은 개발 서버를 시작하고 작업하는 동안 브라우저에서 사이트의 실시간 업데이트 미리보기를 제공합니다.

Terminal window
# 개발 서버를 시작합니다.
npx astro dev

터미널에 astro --help를 입력하면 사용 가능한 모든 명령 목록을 표시할 수 있습니다.

Terminal window
npx astro --help

터미널에 다음 메시지가 표시됩니다.

Terminal window
astro [command] [...flags]
Commands
add Add an integration.
build Build your project and write it to disk.
check Check your project for errors.
dev Start the development server.
docs Open documentation in your web browser.
info List info about your current Astro setup.
preview Preview your build locally.
sync Generate content collection types.
preferences Configure user preferences.
telemetry Configure telemetry settings.
Global Flags
--config <path> Specify your config file.
--root <path> Specify your project root folder.
--site <url> Specify your project site.
--base <pathname> Specify your project base.
--verbose Enable verbose logging.
--silent Disable all logging.
--version Show the version number and exit.
--open Open the app in the browser on server start.
--help Show this help message.

이러한 명령의 더 짧은 버전에 package.json의 스크립트를 사용할 수도 있습니다. 스크립트를 사용하면 npm run build와 같이 다른 프로젝트에서 익숙할 수 있는 동일한 명령을 사용할 수 있습니다.

가장 일반적인 astro 명령 (astro dev, astro build, astro preview)에 대한 다음 스크립트는 create astro 마법사를 사용하여 프로젝트를 생성할 때 자동으로 추가됩니다.

Astro 수동 설치 지침을 따르면 이러한 스크립트를 직접 추가하라는 메시지가 표시됩니다. 자주 사용하는 명령에 대해 수동으로 이 목록에 더 많은 스크립트를 추가할 수도 있습니다.

package.json
{
"scripts": {
"dev": "astro dev",
"start": "astro dev",
"build": "astro build",
"preview": "astro preview"
}
}

플래그 없이 이러한 astro 명령이나 이를 실행하는 스크립트를 자주 사용하게 됩니다. 명령의 동작을 사용자 정의하려면 명령에 플래그를 추가하세요. 예를 들어, 다른 포트에서 개발 서버를 시작하거나 디버깅을 위해 자세한 로그를 사용하여 사이트를 구축할 수 있습니다.

Terminal window
# `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
npm run start -- --port 8080
# `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
npm run build -- --verbose

Astro의 개발 서버를 실행합니다. 이는 자산을 번들로 묶지 않는 로컬 HTTP 서버입니다. HMR (Hot Module Replacement)을 사용하여 편집기에 변경 사항을 저장할 때 브라우저를 업데이트합니다.

배포용 사이트를 빌드합니다. 기본적으로 이는 정적 파일을 생성하여 dist/ 디렉터리에 저장합니다. SSR이 활성화된 경우, 사이트를 제공하는 데 필요한 서버 파일이 생성됩니다.

아래에 설명된 공통 플래그와 결합할 수 있습니다.

astro build를 실행하여 생성된 정적 디렉터리 (기본적으로 dist/)의 콘텐츠를 제공하기 위해 로컬 서버를 시작합니다.

이 명령을 사용하면 빌드 후 로컬에서 사이트를 미리 보고 배포하기 전에 빌드 출력에서 ​​오류를 확인할 수 있습니다. 프로덕션 환경에서 실행되도록 설계되지 않았습니다. 프로덕션 호스팅에 대한 도움이 필요하면 Astro 웹사이트 배포 안내서를 확인하세요.

Astro 1.5.0부터 astro preview는 이를 지원하는 어댑터를 사용하는 경우 SSR 빌드에서도 작동합니다. 현재는 Node 어댑터에서만 astro preview를 지원합니다.

아래에 설명된 공통 플래그와 결합할 수 있습니다.

프로젝트에 대해 진단 (예: .astro 파일 내 타입 검사)을 실행하고 오류를 콘솔에 보고합니다. 오류가 발견되면 프로세스는 1 코드와 함께 종료됩니다.

이 명령은 CI 워크플로에서 사용하기 위한 것입니다.

플래그

명령의 동작을 사용자 정의하려면 이러한 플래그를 사용하세요.

이 명령은 프로젝트의 변경 사항을 감시하고 오류를 보고합니다.

Astro의 타입 검사에 대해 자세히 알아보세요.

Added in: astro@2.0.0

모든 Astro 모듈에 대한 TypeScript 타입을 생성합니다. 이는 타입 추론을 위한 src/env.d.ts 파일을 설정하고 Content Collections APIastro:content 모듈을 정의합니다.

구성에 통합을 추가합니다. 통합 안내서에서 자세히 알아보세요.

터미널에서 직접 Astro 문서 웹사이트를 시작합니다.

현재 Astro 환경에 대한 유용한 정보를 보고합니다. 이슈를 열 때 정보를 제공하는 데 유용합니다.

Terminal window
astro info

Example output:

Astro v3.0.12
Node v20.5.1
System macOS (arm64)
Package Manager pnpm
Output server
Adapter @astrojs/vercel/serverless
Integrations none

astro preferences 명령으로 사용자 기본 설정을 관리하세요. 프로젝트에 참여하는 모든 사람의 동작을 변경하는 astro.config.mjs 파일과 달리 사용자 기본 설정은 개별 Astro 사용자에게만 적용됩니다.

사용자 기본 설정은 기본적으로 현재 프로젝트로 범위가 지정되며 로컬 .astro/settings.json 파일에 저장됩니다.

--global 플래그를 사용하면 현재 시스템의 모든 Astro 프로젝트에 사용자 기본 설정을 적용할 수도 있습니다. 전역 사용자 기본 설정은 운영 체제별 위치에 저장됩니다.

예를 들어, 특정 Astro 프로젝트에서 devToolbar를 비활성화하려면:

Terminal window
astro preferences disable devToolbar

현재 머신의 모든 Astro 프로젝트에서 devToolbar를 비활성화하려면:

Terminal window
astro preferences disable --global devToolbar

devToolbar는 나중에 다음을 사용하여 활성화할 수 있습니다.

Terminal window
astro preferences enable devToolbar

reset 명령은 기본 설정을 기본값으로 재설정합니다.

Terminal window
astro preferences reset devToolbar

list 명령은 구성 가능한 모든 사용자 기본 설정의 현재 설정을 출력합니다. 또한 기계가 읽을 수 있는 --json 출력을 지원합니다.

Terminal window
astro preferences list

현재 CLI 사용자에 대한 원격 측정 구성을 설정합니다. 원격 측정은 Astro 팀에 Astro 기능이 가장 자주 사용되는 통찰력을 제공하는 익명 데이터입니다. 자세한 내용은 Astro의 원격 측정 페이지를 참조하세요.

다음 CLI 명령을 사용하여 원격 측정을 비활성화할 수 있습니다.

Terminal window
astro telemetry disable

나중에 다음을 사용하여 원격 측정을 다시 활성화할 수 있습니다.

Terminal window
astro telemetry enable

reset 명령은 원격 측정 데이터를 초기화합니다.

Terminal window
astro telemetry reset

프로젝트 루트의 경로를 지정합니다. 지정하지 않으면 현재 작업 디렉터리가 루트로 간주됩니다.

루트는 Astro 구성 파일을 찾는 데 사용됩니다.

Terminal window
astro --root myRootFolder/myProjectFolder dev

프로젝트 루트를 기준으로 구성 파일의 경로를 지정합니다. 기본값은 astro.config.mjs입니다. 구성 파일에 다른 이름을 사용하거나 구성 파일이 다른 폴더에 있는 경우 이 방법을 사용하세요.

Terminal window
astro --config config/astro.config.mjs dev

Added in: astro@3.3.0

프로젝트에 대한 outDir를 구성합니다. 이 플래그를 전달하면 astro.config.mjs 파일에 outDir 값이 있는 경우 이를 재정의합니다.

프로젝트에 대한 site를 구성합니다. 이 플래그를 전달하면 astro.config.mjs 파일에 site 값이 있는 경우 이를 재정의합니다.

Added in: astro@1.4.1

프로젝트에 대한 base를 구성합니다. 이 플래그를 전달하면 astro.config.mjs 파일에 base 값이 있는 경우 이를 재정의합니다.

개발 서버와 미리보기 서버를 실행할 포트를 지정합니다. 기본값은 4321입니다.

--host [선택적 호스트 주소]

섹션 제목: --host [선택적 호스트 주소]

개발 서버와 미리 보기 서버가 수신 대기해야 하는 네트워크 IP 주소 (예: localhost가 아닌 IP)를 설정합니다. 이는 개발 중 휴대폰과 같은 로컬 장치에서 프로젝트를 테스트하는 데 유용할 수 있습니다.

  • --host — LAN 및 공용 주소를 포함한 모든 주소에서 수신
  • --host <사용자 정의 주소><사용자 정의 주소>에 네트워크 IP 주소 노출

문제를 디버깅할 때 유용한 자세한 로깅을 활성화합니다.

콘솔 출력 없이 서버를 실행하는 자동 로깅을 활성화합니다.

이 플래그를 사용하여 astro CLI에 대한 정보를 얻으세요.

Astro 버전 번호를 출력하고 종료합니다.

서버 시작 시 브라우저에서 앱을 자동으로 엽니다. 열려는 URL을 지정하기 위해 전체 URL 문자열 (예: --open http://example.com) 또는 경로 이름 (예: --open /about)을 전달할 수 있습니다.

도움말 메시지를 출력하고 종료합니다.

Astro를 실행할 때 더 많은 제어가 필요한 경우 "astro" 패키지는 프로그래밍 방식으로 CLI 명령을 실행하기 위해 API를 내보냅니다.

이러한 API는 실험적이며 API 시그니처가 변경될 수 있습니다. 모든 업데이트는 Astro 변경 로그에 언급되며 아래 정보는 항상 최신 정보를 표시합니다.

AstroInlineConfig 타입은 아래의 모든 명령 API에서 사용됩니다. 이는 사용자 Astro 구성 타입에서 확장됩니다.

interface AstroInlineConfig extends AstroUserConfig {
configFile?: string | false;
mode?: "development" | "production";
logLevel?: "debug" | "info" | "warn" | "error" | "silent";
}

타입: string | false
기본값: undefined

Astro 구성 파일의 사용자 정의 경로입니다.

이 값이 undefined이거나 (기본값) 설정되지 않은 경우 Astro는 root를 기준으로 astro.config.(js,mjs,ts) 파일을 검색하고 발견되면 구성 파일을 로드합니다.

상대 경로가 설정되면 현재 작업 디렉터리를 기반으로 확인됩니다.

구성 파일 로드를 비활성화하려면 false로 설정하세요.

이 객체에 전달된 인라인 구성은 로드된 사용자 구성과 병합될 때 가장 높은 우선순위를 갖습니다.

타입: "development" | "production"
기본값: astro dev를 실행할 때 "development", astro build를 실행할 때 "production"

“development” 또는 “production” 코드를 생성하기 위해 사이트를 빌드할 때 사용되는 모드입니다.

타입: "debug" | "info" | "warn" | "error" | "silent"
기본값: "info"

Astro가 기록한 메시지를 필터링하는 로깅 수준입니다.

  • "debug": 자세한 디버깅 진단을 포함한 모든 것을 기록합니다.
  • "info": 정보 메시지, 경고, 오류를 기록합니다.
  • "warn": 경고 및 오류를 기록합니다.
  • "error": 오류만 기록합니다.
  • "silent": 아무것도 기록하지 않습니다.

타입: (inlineConfig: AstroInlineConfig) => AstroDevServer

astro dev와 유사하게 Astro의 개발 서버를 실행합니다.

import { dev } from "astro";
const devServer = await dev({
root: "./my-project",
});
// 필요한 경우 서버를 중지합니다.
await devServer.stop();

타입: (inlineConfig: AstroInlineConfig) => void

astro build와 유사하게 배포용 사이트를 빌드합니다.

import { build } from "astro";
await build({
root: "./my-project",
});

타입: (inlineConfig: AstroInlineConfig) => AstroPreviewServer

astro preview와 유사하게, 정적 dist/ 디렉터리를 제공하기 위해 로컬 서버를 시작합니다.

import { preview } from "astro";
const previewServer = await preview({
root: "./my-project",
});
// 필요한 경우 서버를 중지합니다.
await previewServer.stop();

타입: (inlineConfig: AstroInlineConfig) => number

astro sync와 유사하게 모든 Astro 모듈에 대해 TypeScript 타입을 생성합니다.

import { sync } from "astro";
const exitCode = await sync({
root: "./my-project",
});
process.exit(exitCode)