命令行（CLI）命令

你可以使用 Astro 提供的命令行界面（CLI）在终端窗口中开发、构建和预览你的项目。

astro 命令

通过你偏好的包管理器运行本页记录的某个 命令，并可选择性地在其后附加任何 标志，即可使用 CLI。标志可以自定义命令的行为。

你最常使用的命令之一是 astro dev。此命令会启动开发服务器，并在你工作时在浏览器中提供网站的实时更新预览。

npm

# start the development server
npx astro dev

pnpm

# start the development server
pnpm astro dev

Yarn

# start the development server
yarn astro dev

你可以在终端中输入 astro --help 来显示所有可用命令的列表。

npm

npx astro --help

pnpm

pnpm astro --help

Yarn

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 标志，以获取该命令的所有可用标志列表。

npm

# get a list of all flags for the `dev` command
npm run dev -- --help

pnpm

# get a list of all flags for the `dev` command
pnpm dev --help

Yarn

# get a list of all flags for the `dev` command
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.

注意

对于 npm，在任何标志前都需要额外的 --，以便将你的标志传递给 astro 命令。

package.json 脚本

你也可以在 package.json 中使用脚本来简化这些命令。使用脚本可以让你使用你可能在其他项目中熟悉的相同命令，例如 npm run build。

当你使用 create astro 向导创建项目时，以下用于最常见的 astro 命令（astro dev、astro build 和 astro preview）的脚本会自动为你添加。

当你按照说明手动安装 Astro时，系统会指示你自行添加这些脚本。你也可以手动向此列表添加更多脚本，用于你经常使用的任何命令。

package.json

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

你通常会不带任何标志地使用这些 astro 命令或运行它们的脚本。当你想要自定义命令的行为时，请向命令添加标志。例如，你可能希望在不同的端口上启动开发服务器，或者为了调试而使用详细日志来构建你的站点。

npm

# run the dev server on port 8080 using the `dev` script in `package.json`
npm run dev -- --port 8080

# build your site with verbose logs using the `build` script in `package.json`
npm run build -- --verbose

pnpm

# run the dev server on port 8080 using the `dev` script in `package.json`
pnpm dev --port 8080

# build your site with verbose logs using the `build` script in `package.json`
pnpm build --verbose

Yarn

# run the dev server on port 8080 using the `dev` script in `package.json`
yarn dev --port 8080

# build your site with verbose logs using the `build` script in `package.json`
yarn build --verbose

astro dev

运行 Astro 的开发服务器。这是一个本地 HTTP 服务器，它不打包资源。它使用热模块替换（HMR）来在你保存编辑器中的更改时更新你的浏览器。

在运行 Astro 开发服务器的终端中，可以使用以下热键：

• s + enter 同步内容层数据（内容和类型）。
• o + enter 在浏览器中打开你的 Astro 站点。
• q + enter 退出开发服务器。

astro build

为部署构建你的站点。默认情况下，这会生成静态文件并将其放入 dist/ 目录中。如果任何路由是按需渲染的，这将生成必要的服务器文件来为你的站点提供服务。

标志

该命令接受通用标志和以下附加标志：

--devOutput

添加于： 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>

指定要检查的不同根目录。默认使用当前工作目录。

--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

指定在监视模式下，在检查之间不要清除输出。

--noSync

指定在检查项目之前不运行 astro sync。

阅读更多关于在 Astro 中进行类型检查的内容。

astro sync

新增于： astro@2.0.0

提示

运行 astro dev、astro build 或 astro check 也会运行 sync 命令。

为所有 Astro 模块生成 TypeScript 类型。这会设置一个.astro/types.d.ts 文件用于类型推断，并为依赖于生成类型的功能定义模块：

• 用于 内容集合 API 的 astro:content 模块。
• 用于 Astro DB 的 astro:db 模块。
• 用于 Astro Env 的 astro:env 模块。
• 用于 Astro Actions 的 astro:actions 模块。

astro add

向你的配置中添加一个集成。在集成指南中阅读更多内容。

astro docs

直接从终端启动 Astro 文档网站。

astro info

报告有关你当前 Astro 环境的有用信息。在提出 issue 时提供信息很有用。

astro info

输出示例：

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 用户的，不像 astro.config.mjs 文件那样会改变项目中每个人的行为。

默认情况下，用户偏好设置的作用域是当前项目，存储在本地的 .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 项目中禁用开发工具栏：

astro preferences disable devToolbar

要在当前机器上的所有 Astro 项目中禁用开发工具栏：

astro preferences disable --global 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

想在 CI 环境中禁用遥测吗？

将 astro telemetry disable 命令添加到你的 CI 脚本中，或设置 ASTRO_TELEMETRY_DISABLED 环境变量。

通用标志

--root <path>

指定项目根目录的路径。如果未指定，则假定当前工作目录为根目录。

根目录用于查找 Astro 配置文件。

astro --root myRootFolder/myProjectFolder dev

--config <path>

指定相对于项目根目录的配置文件的路径。默认为 astro.config.mjs。如果你的配置文件使用不同的名称或位于其他文件夹中，请使用此标志。

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

--force <string>

添加于： astro@5.0.0

清除内容层缓存，强制进行完全重建。

--mode <string>

添加于： astro@5.0.0

为你的项目配置内联配置 mode。

--outDir <path>

添加于： astro@3.3.0

为你的项目配置 outDir。传递此标志将覆盖 astro.config.mjs 文件中的 outDir 值（如果存在）。

--site <url>

为你的项目配置 site。传递此标志将覆盖 astro.config.mjs 文件中的 site 值（如果存在）。

--base <pathname>

添加于： astro@1.4.1

为你的项目配置 base。传递此标志将覆盖 astro.config.mjs 文件中的 base 值（如果存在）。

--port <number>

指定运行开发服务器和预览服务器的端口。默认为 4321。

--host [可选主机地址]

设置开发服务器和预览服务器应侦听的网络 IP 地址（即非 localhost IP）。这对于在开发过程中在本地设备（如手机）上测试你的项目非常有用。

• --host — 监听所有地址，包括局域网和公共地址
• --host <custom-address> — 在网络 IP 地址 <custom-address> 上公开

注意

不要使用 --host 标志在生产环境中公开开发服务器和预览服务器。这些服务器仅设计用于在开发站点时本地使用。

--allowed-hosts

添加于： astro@5.4.0

指定在 dev 或 preview 模式下 Astro 允许响应的主机名。可以传递一个逗号分隔的主机名列表，或者传递 true 来允许任何主机名。

有关更多信息，包括允许主机名的安全隐患，请参阅 Vite 的 allowedHosts 功能。

--verbose

启用详细日志记录，这在调试问题时很有帮助。

--silent

启用静默日志记录，这将在没有任何控制台输出的情况下运行服务器。

--open

服务器启动时在浏览器中自动打开应用程序。可以传递一个完整的 URL 字符串（例如 --open http://example.com）或一个路径名（例如 --open /about）来指定要打开的 URL。

全局标志

使用这些标志获取有关 astro CLI 的信息。

--version

打印 Astro 版本号并退出。

--help

打印帮助信息并退出。