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.
       create-key  Create a cryptography key
              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 TypeScript types for all Astro modules.
      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.
           --help  Show this help message.

명령 뒤에 --help 플래그를 추가하면 해당 명령의 모든 플래그를 확인할 수 있습니다.

# `dev` 명령에 대한 모든 플래그 목록을 가져옵니다.
npm run dev -- --help

# `dev` 명령에 대한 모든 플래그 목록을 가져옵니다.
pnpm dev --help

# `dev` 명령에 대한 모든 플래그 목록을 가져옵니다.
yarn dev --help

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

astro dev [...flags]

Flags
                 --port  Specify which port to run on. Defaults to 4321.
                 --host  Listen on all addresses, including LAN and public addresses.
--host <custom-address>  Expose on a network IP address at <custom-address>
                 --open  Automatically open the app in the browser on server start
                --force  Clear the content layer cache, forcing a full rebuild.
            --help (-h)  See all available flags.

`package.json` 스크립트

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

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

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

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

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

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

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

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

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

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

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

`astro dev`

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

`astro build`

배포용 사이트를 빌드합니다. 기본적으로 이는 정적 파일을 생성하여 dist/ 디렉터리에 저장합니다. 모든 라우트가 요청 시 렌더링되는 경우, 사이트를 제공하는 데 필요한 서버 파일이 생성됩니다.

플래그

이 명령어는 공통 플래그와 다음과 같은 추가 플래그를 허용합니다:

`--devOutput`

Added in: astro@5.0.0

개발 기반 빌드를 출력하며 이는 astro dev에서 변환된 코드와 유사합니다. 이는 추가적인 디버깅 정보가 포함된 빌드 전용 문제를 테스트하는 데 유용할 수 있습니다.

`astro preview`

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

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

Astro 1.5.0 이후부터 Node 어댑터가 요청 시 렌더링으로 생성된 빌드에 대해 astro preview를 지원합니다.

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

`astro check`

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

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

플래그

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

`--watch`

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

`--root <path-to-dir>`

check 명령을 실행할 다른 루트 디렉터리를 지정합니다. 기본적으로 현재 작업 디렉터리를 사용합니다.

`--tsconfig <path-to-file>`

수동으로 사용할 tsconfig.json 파일을 지정합니다. 제공되지 않은 경우 Astro는 구성을 찾으려고 시도하거나 프로젝트의 구성을 자동으로 추론합니다.

`--minimumFailingSeverity <error|warning|hint>`

오류 코드와 함께 종료하는 데 필요한 최소 심각도를 지정합니다. 기본값은 error입니다.

예를 들어 astro check --minimumFailingSeverity warning 실행 시, 경고가 감지되면 명령이 오류와 함께 종료됩니다.

`--minimumSeverity <error|warning|hint>`

출력할 최소 심각도를 지정합니다. 기본값은 hint입니다.

예를 들어 astro check --minimumSeverity warning을 실행하면 오류와 경고가 표시되지만 힌트는 표시되지 않습니다.

`--preserveWatchOutput`

감시 모드에서 check 사이의 출력을 지우지 않도록 지정합니다.

`--noSync`

프로젝트를 검사하기 전에 astro sync를 실행하지 않도록 지정합니다.

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

`astro sync`

Added in: astro@2.0.0

모든 Astro 모듈에 대한 TypeScript 타입을 생성합니다. 이는 타입 추론을 위한 .astro/types.d.ts 파일을 설정하고 생성된 타입에 의존하는 기능에 대한 모듈을 정의합니다.

astro:content 콘텐츠 컬렉션 API를 위한 모듈
astro:db Astro DB를 위한 모듈
실험적 Astro Env를 위한 astro:env 모듈
Astro Actions를 위한 astro:actions 모듈

`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 프로젝트에 사용자 기본 설정을 적용할 수도 있습니다. 전역 사용자 기본 설정은 운영 체제별 위치에 저장됩니다.

사용 가능한 기본 설정

devToolbar — 브라우저에서 개발 툴바를 활성화하거나 비활성화합니다. (기본값: true)
checkUpdates — Astro CLI에 대한 자동 업데이트 확인을 활성화 또는 비활성화합니다. (기본값: true)

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

astro preferences list

터미널 출력 예시:

기본 설정	값
devToolbar.enabled	true
checkUpdates.enabled	true

기본값을 enable, disable, 또는 reset으로 설정할 수 있습니다.

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

astro preferences disable devToolbar

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

astro preferences disable --global devToolbar

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

astro preferences enable devToolbar

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

astro preferences reset devToolbar

`astro telemetry`

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

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

astro telemetry disable

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

astro telemetry enable

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

astro telemetry reset

공통 플래그

`--root <path>`

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

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

astro --root myRootFolder/myProjectFolder dev

`--config <path>`

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

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

`--force <string>`

Added in: astro@5.0.0

콘텐츠 레이어 캐시를 지우고 전체 리빌드를 강제 실행합니다.

`--mode <string>`

Added in: astro@5.0.0

프로젝트의 인라인 mode 구성을 설정합니다.

`--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 값이 있는 경우 이를 재정의합니다.

`--port <number>`

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

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

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

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

`--verbose`

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

`--silent`

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

`--open`

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

전역 플래그

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

`--version`

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

`--help`

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

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

CLI 명령

astro 명령

package.json 스크립트

astro dev

astro build

플래그

--devOutput

astro preview

astro check

플래그

--watch

--root <path-to-dir>

--tsconfig <path-to-file>

--minimumFailingSeverity <error|warning|hint>

--minimumSeverity <error|warning|hint>

--preserveWatchOutput

--noSync

astro sync

astro add

astro docs

astro info

astro preferences

사용 가능한 기본 설정

astro telemetry

공통 플래그

--root <path>

--config <path>

--force <string>

--mode <string>

--outDir <path>

--site <url>

--base <pathname>

--port <number>

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

--verbose

--silent

--open

전역 플래그

--version

--help

`astro` 명령

`package.json` 스크립트

`astro dev`

`astro build`

`--devOutput`

`astro preview`

`astro check`

`--watch`

`--root <path-to-dir>`

`--tsconfig <path-to-file>`

`--minimumFailingSeverity <error|warning|hint>`

`--minimumSeverity <error|warning|hint>`

`--preserveWatchOutput`

`--noSync`

`astro sync`

`astro add`

`astro docs`

`astro info`

`astro preferences`

`astro telemetry`

`--root <path>`

`--config <path>`

`--force <string>`

`--mode <string>`

`--outDir <path>`

`--site <url>`

`--base <pathname>`

`--port <number>`

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

`--verbose`

`--silent`

`--open`

`--version`

`--help`