CLI 命令

你可以使用 Astro 提供的命令行接口 (CLI) 从终端窗口开发、构建和预览项目。

¥You can use the Command-Line Interface (CLI) provided by Astro to develop, build, and preview your project from a terminal window.

`astro` 命令

¥astro commands

通过使用你首选的包管理器运行此页面上记录的命令之一来使用 CLI，可选择后跟任何标志。标志定制命令的行为。

¥Use the CLI by running one of the commands documented on this page with your preferred package manager, optionally followed by any flags. Flags customize the behavior of a command.

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

¥One of the commands you’ll use most often is astro dev. This command starts the development server and gives you a live, updating preview of your site in a browser as you work:

# start the development server
npx astro dev

# start the development server
pnpm astro dev

# start the development server
yarn astro dev

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

¥You can type astro --help in your terminal to display a list of all available commands:

npx astro --help

pnpm astro --help

yarn astro --help

以下消息将显示在你的终端中：

¥The following message will display in your terminal:

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

¥You can add the --help flag after any command to get a list of all the flags for that command.

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

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

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

以下消息将显示在你的终端中：

¥The following message will display in your terminal:

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 scripts

你还可以使用 package.json 中的脚本来实现这些命令的较短版本。使用脚本允许你使用你在其他项目（例如 npm run build）中可能熟悉的相同命令。

¥You can also use scripts in package.json for shorter versions of these commands. Using a script allows you to use the same commands that you may be familiar with from other projects, such as npm run build.

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

¥The following scripts for the most common astro commands (astro dev, astro build, and astro preview) are added for you automatically when you create a project using the create astro wizard.

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

¥When you follow the instructions to install Astro manually, you are instructed to add these scripts yourself. You can also add more scripts to this list manually for any commands you use frequently.

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

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

¥You will often use these astro commands, or the scripts that run them, without any flags. Add flags to the command when you want to customize the command’s behavior. For example, you may wish to start the development server on a different port, or build your site with verbose logs for debugging.

# 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

# 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

# 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) 来更新你的浏览器。

¥Runs Astro’s development server. This is a local HTTP server that doesn’t bundle assets. It uses Hot Module Replacement (HMR) to update your browser as you save changes in your editor.

`astro build`

构建你的站点以进行部署。默认情况下，这将生成静态文件并将它们放置在 dist/ 目录中。如果任何路由是渲染于需求，这将生成为你的网站提供服务所需的服务器文件。

¥Builds your site for deployment. By default, this will generate static files and place them in a dist/ directory. If any routes are rendered on demand, this will generate the necessary server files to serve your site.

标志

¥Flags

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

¥The command accepts common flags and the following additional flags:

`--devOutput`

Added in: astro@5.0.0

输出基于开发的构建，类似于 astro dev 中转换的代码。这可用于测试仅构建问题并包含其他调试信息。

¥Outputs a development-based build similar to code transformed in astro dev. This can be useful to test build-only issues with additional debugging information included.

`astro preview`

启动本地服务器以提供通过运行 astro build 创建的静态目录（默认为 dist/）的内容。

¥Starts a local server to serve the contents of your static directory (dist/ by default) created by running astro build.

此命令允许你在本地构建后预览你的站点，以便在部署之前捕获构建输出中的任何错误。它不是为在生产中运行而设计的。如需生产托管方面的帮助，请查看我们的部署 Astro 网站指南。

¥This command allows you to preview your site locally after building to catch any errors in your build output before deploying it. It is not designed to be run in production. For help with production hosting, check out our guide on Deploying an Astro Website.

自 Astro 1.5.0 起，节点适配器支持使用按需渲染生成的构建的 astro preview。

¥Since Astro 1.5.0, the Node adapter supports astro preview for builds generated with on-demand rendering.

可以与下面记录的通用标志结合使用。

¥Can be combined with the common flags documented below.

`astro check`

针对你的项目运行诊断（例如 .astro 文件中的类型检查）并向控制台报告错误。如果发现任何错误，该过程将以代码 1 退出。

¥Runs diagnostics (such as type-checking within .astro files) against your project and reports errors to the console. If any errors are found the process will exit with a code of 1.

该命令旨在用于 CI 工作流程。

¥This command is intended to be used in CI workflows.

Flags

使用这些标志来自定义命令的行为。

¥Use these flags to customize the behavior of the command.

`--watch`

该命令将监视项目中的任何更改，并报告任何错误。

¥The command will watch for any changes in your project, and will report any errors.

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

指定要检查的其他根目录。默认情况下使用当前工作目录。

¥Specifies a different root directory to check. Uses the current working directory by default.

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

指定要手动使用的 tsconfig.json 文件。如果没有提供，Astro 将尝试查找配置，或自动推断项目的配置。

¥Specifies a tsconfig.json file to use manually. If not provided, Astro will attempt to find a config, or infer the project’s config automatically.

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

指定以错误代码退出所需的最低严重性。默认为 error。

¥Specifies the minimum severity needed to exit with an error code. Defaults to error.

例如，如果检测到任何警告，运行 astro check --minimumFailingSeverity warning 将导致命令退出并出现错误。

¥For example, running astro check --minimumFailingSeverity warning will cause the command to exit with an error if any warnings are detected.

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

指定要输出的最低严重性。默认为 hint。

¥Specifies the minimum severity to output. Defaults to hint.

例如，运行 astro check --minimumSeverity warning 将显示错误和警告，但不显示提示。

¥For example, running astro check --minimumSeverity warning will show errors and warning, but not hints.

`--preserveWatchOutput`

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

¥Specifies not to clear the ouput between checks when in watch mode.

`--noSync`

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

¥Specifies not to run astro sync before checking the project.

`astro sync`

Added in: astro@2.0.0

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

¥Generates TypeScript types for all Astro modules. This sets up a .astro/types.d.ts file for type inferencing, and defines modules for features that rely on generated types:

内容集 API 的 astro:content 模块。
Astro DB 的 astro:db 模块。
Astro Env 的 astro:env 模块。
Astro 操作的 astro:actions 模块

`astro add`

将集成添加到你的配置中。阅读集成指南中的更多内容。

¥Adds an integration to your configuration. Read more in the integrations guide.

`astro docs`

直接从终端启动 Astro Docs 网站。

¥Launches the Astro Docs website directly from the terminal.

`astro info`

报告有关你当前 Astro 环境的有用信息。对于在打开问题时提供信息很有用。

¥Reports useful information about your current Astro environment. Useful for providing information when opening an issue.

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

¥Manage user preferences with the astro preferences command. User preferences are specific to individual Astro users, unlike the astro.config.mjs file which changes behavior for everyone working on a project.

默认情况下，用户首选项的范围仅限于当前项目，存储在本地 .astro/settings.json 文件中。

¥User preferences are scoped to the current project by default, stored in a local .astro/settings.json file.

使用 --global 标志，用户首选项也可以应用于当前计算机上的每个 Astro 项目。全局用户首选项存储在操作系统特定的位置。

¥Using the --global flag, user preferences can also be applied to every Astro project on the current machine. Global user preferences are stored in an operating system-specific location.

Available preferences

devToolbar — 在浏览器中启用或禁用开发工具栏。（默认：true）
checkUpdates — 启用或禁用 Astro CLI 的自动更新检查。（默认：true）

list 命令打印所有可配置用户首选项的当前设置。它还支持机器可读的 --json 输出。

¥The list command prints the current settings of all configurable user preferences. It also supports a machine-readable --json output.

astro preferences list

示例终端输出：

¥Example terminal output:

偏好设置	值
devToolbar.enabled	true
checkUpdates.enabled	true

你可以将 enable、disable 或 reset 首选项设置为其默认值。

¥You can enable, disable, or reset preferences to their default.

例如，要禁用特定 Astro 项目中的 devToolbar：

¥For example, to disable the devToolbar in a specific Astro project:

astro preferences disable devToolbar

要禁用当前计算机上所有 Astro 项目中的 devToolbar：

¥To disable the devToolbar in all Astro projects on the current machine:

astro preferences disable --global devToolbar

稍后可以通过以下方式启用 devToolbar：

¥The devToolbar can later be enabled with:

astro preferences enable devToolbar

reset 命令将首选项重置为其默认值：

¥The reset command resets a preference to its default value:

astro preferences reset devToolbar

`astro telemetry`

为当前 CLI 用户设置遥测配置。遥测是匿名数据，可让 Astro 团队深入了解最常使用的 Astro 功能。欲了解更多信息，请参阅 Astro 的遥测页面。

¥Sets telemetry configuration for the current CLI user. Telemetry is anonymous data that provides the Astro team insights into which Astro features are most often used. For more information see Astro’s telemetry page.

可以使用以下 CLI 命令禁用遥测：

¥Telemetry can be disabled with this CLI command:

astro telemetry disable

稍后可以通过以下方式重新启用遥测：

¥Telemetry can later be re-enabled with:

astro telemetry enable

reset 命令重置遥测数据：

¥The reset command resets the telemetry data:

astro telemetry reset

常用标志

¥Common flags

`--root <path>`

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

¥Specifies the path to the project root. If not specified, the current working directory is assumed to be the root.

root 用于查找 Astro 配置文件。

¥The root is used for finding the Astro configuration file.

astro --root myRootFolder/myProjectFolder dev

`--config <path>`

指定相对于项目根目录的配置文件的路径。默认为 astro.config.mjs。如果你对配置文件使用不同的名称或将配置文件放在另一个文件夹中，请使用此选项。

¥Specifies the path to the config file relative to the project root. Defaults to astro.config.mjs. Use this if you use a different name for your configuration file or have your config file in another folder.

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

`--force <string>`

Added in: astro@5.0.0

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

¥Clear the content layer cache, forcing a full rebuild.

`--mode <string>`

Added in: astro@5.0.0

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

¥Configures the mode inline config for your project.

`--outDir <path>`

Added in: astro@3.3.0

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

¥Configures the outDir for your project. Passing this flag will override the outDir value in your astro.config.mjs file, if one exists.

`--site <url>`

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

¥Configures the site for your project. Passing this flag will override the site value in your astro.config.mjs file, if one exists.

`--base <pathname>`

Added in: astro@1.4.1

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

¥Configures the base for your project. Passing this flag will override the base value in your astro.config.mjs file, if one exists.

`--port <number>`

指定在哪个端口上运行开发服务器和预览服务器。默认为 4321。

¥Specifies which port to run the dev server and preview server on. Defaults to 4321.

`--host [optional host address]`

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

¥Sets which network IP addresses the dev server and preview server should listen on (i.e. non-localhost IPs). This can be useful for testing your project on local devices like a mobile phone during development.

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

`--verbose`

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

¥Enables verbose logging, which is helpful when debugging an issue.

`--silent`

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

¥Enables silent logging, which will run the server without any console output.

`--open`

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

¥Automatically opens the app in the browser on server start. Can be passed a full URL string (e.g. --open http://example.com) or a pathname (e.g. --open /about) to specify the URL to open.

全局标志

¥Global flags

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

¥Use these flags to get information about the astro CLI.

`--version`

打印 Astro 版本号并退出。

¥Prints the Astro version number and exits.

`--help`

打印帮助消息并退出。

¥Prints the help message and exits.

CLI 命令

astro 命令

package.json 脚本

astro dev

astro build

标志

--devOutput

astro preview

astro check

Flags

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

Available preferences

astro telemetry

常用标志

--root <path>

--config <path>

--force <string>

--mode <string>

--outDir <path>

--site <url>

--base <pathname>

--port <number>

--host [optional host address]

--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 [optional host address]`

`--verbose`

`--silent`

`--open`

`--version`

`--help`