CLI 명령

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

`astro` 명령

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

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

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

# 개발 서버를 시작합니다.
pnpm astro dev

# 개발 서버를 시작합니다.
yarn astro dev

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

npx astro --help

pnpm astro --help

yarn astro --help

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

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` 스크립트

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

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

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

{
  "scripts": {
    "dev": "astro dev",
    "start": "astro dev",
    "build": "astro build",
    "preview": "astro preview"
  }
}

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

# `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
npm run start -- --port 8080

# `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
npm run build -- --verbose

# `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
pnpm start --port 8080

# `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
pnpm build --verbose

# `package.json` 파일의 `start` 스크립트를 사용하여 포트 8080에서 개발 서버를 실행합니다.
yarn start --port 8080

# `package.json` 파일의 `build` 스크립트를 사용하여 자세한 로그로 사이트를 빌드합니다.
yarn build --verbose

`astro dev`

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

플래그

Astro 개발 서버의 동작을 사용자 정의하려면 이 플래그를 사용하세요. 다른 Astro 명령과 공유되는 플래그는 아래의 공통 플래그를 참조하세요.

`--port <number>`

실행할 포트를 지정합니다. 기본값은 4321입니다.

`--host [optional host address]`

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

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

`astro build`

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

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

`astro preview`

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

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

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

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

`astro check`

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

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

플래그

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

`--watch`

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

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

`astro sync`

Added in: astro@2.0.0

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

`astro add`

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

`astro docs`

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

`astro info`

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

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

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

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

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

astro preferences disable devToolbar

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

astro preferences disable --global devToolbar

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

astro preferences enable devToolbar

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

astro preferences reset devToolbar

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

astro preferences list

`astro telemetry`

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

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

astro telemetry disable

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

astro telemetry enable

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

astro telemetry clear

공통 플래그

`--root <path>`

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

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

astro --root myRootFolder/myProjectFolder dev

`--config <path>`

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

astro --config config/astro.config.mjs dev

`--outDir <path>`

Added in: astro@3.3.0

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

`--site <url>`

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

`--base <pathname>`

Added in: astro@1.4.1

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

`--verbose`

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

`--silent`

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

Global flags

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

`--version`

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

`--open`

서버 시작 시 브라우저에서 앱을 자동으로 엽니다.

`--help`

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

고급 API (실험적 기능)

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

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

`AstroInlineConfig`

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

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

`configFile`

타입: string | false
기본값: undefined

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

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

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

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

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

`mode`

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

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

`logLevel`

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

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

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

`dev()`

타입: (inlineConfig: AstroInlineConfig) => AstroDevServer

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

import { dev } from "astro";

const devServer = await dev({
  root: "./my-project",
});

// 필요한 경우 서버를 중지합니다.
await devServer.stop();

`build()`

타입: (inlineConfig: AstroInlineConfig) => void

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

import { build } from "astro";

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

`preview()`

타입: (inlineConfig: AstroInlineConfig) => AstroPreviewServer

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

import { preview } from "astro";

const previewServer = await preview({
  root: "./my-project",
});

// 필요한 경우 서버를 중지합니다.
await previewServer.stop();

`sync()`

타입: (inlineConfig: AstroInlineConfig) => number

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

import { sync } from "astro";

const exitCode = await sync({
  root: "./my-project",
});

process.exit(exitCode)

CLI 명령

astro 명령

package.json 스크립트

astro dev

플래그

--port <number>

--host [optional host address]

astro build

astro preview

astro check

플래그

--watch

astro sync

astro add

astro docs

astro info

astro preferences

astro telemetry

공통 플래그

--root <path>

--config <path>

--outDir <path>

--site <url>

--base <pathname>

--verbose

--silent