CLI 命令

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

通过使用你喜欢的包管理器运行此页面上记录的命令之一来使用 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.
        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。

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

当你按照手动安装 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 -- --drafts

# 使用 `package.json` 中的 `start` 脚本，以端口 8080 启动开发服务器
pnpm start --port 8080

# 使用 `package.json` 中的 `build` 脚本，构建包含草稿页面的网站
pnpm build --drafts

# 使用 `package.json` 中的 `start` 脚本，以端口 8080 启动开发服务器
yarn start --port 8080

# 使用 `package.json` 中的 `build` 脚本，构建包含草稿页面的网站
yarn build --drafts

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

标志

使用这些标志来自定义 Astro 开发服务器的行为。 对于与其他 Astro 命令共享的标志，请参阅下面的通用标志。

指定运行在哪个端口。默认为 3000。

设置开发服务器应该监听哪些网络 IP 地址（即非本地主机 IP）。这对于在开发期间在本地设备（例如手机）上测试你的项目很有用。

• --host——监听所有地址，包括 LAN 和公开地址
• --host [自定义地址]——暴露在 [自定义地址] 的网络 IP 地址上。

构建你的网站以进行部署。默认情况下，这将生成静态文件并将它们放在dist/目录中。如果SSR被启用，这将生成必要的服务器文件为你的网站提供服务。

标志

使用这些标志来自定义构建。 对于与其他 Astro 命令共享的标志，请参阅下面的通用标志。

在构建中包含 Markdown 草稿页面。

启动本地静态文件服务器，为静态的 dist/ 目录提供服务。

此命令对于在部署之前在本地预览你的构建很有用。它不是为在生产环境中运行而设计的。关于生产托管的帮助，请查看我们的部署 Astro 站点指南。

从 Astro 1.5.0 开始，如果你使用支持它的适配器，astro preview也适用于 SSR 构建。 目前，只有 Node 适配器支持 astro preview。

可以与下面文档的通用标志结合使用。

对项目进行检测（比如对 .astro 文件进行类型检查），并向控制台输出错误信息。如果发现任何错误，该进程将以 1 代码退出。

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

标志

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

该命令将监听 .astro 文件的任何更改，并报告任何错误。

📚 阅读更多关于 Astro 的 TypeScript 支持的信息。

添加于： astro@2.0.0

为所有 Astro 模块生成 TypeScript 类型。这会为类型推断设置一个src/env.d.ts文件，并为 内容集合 API 定义 astro:content 模块。

将集成添加到你的配置中。在集成指南中阅读更多信息。

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

显示当前 Astro 环境的有用信息，以便在提交 issue 时提供信息。

astro info

输出示例：

Astro version            v2.6.6
Package manager          pnpm
Platform                 darwin
Architecture             arm64
Adapter                  @astrojs/vercel/serverless
Integrations             None or couldn't determine.

为当前 CLI 用户设置遥测配置。遥测是匿名数据，可让 Astro 团队深入了解最常使用哪些 Astro 功能。

可以通过这个 CLI 命令禁用遥测：

astro telemetry disable

后面也可以随时通过以下方式重新启用遥测：

astro telemetry enable

使用 clear 命令重置遥测数据：

astro telemetry clear

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

根目录是用来寻找 Astro 配置文件的。

astro --root myRootFolder/myProjectFolder dev

指定配置文件的路径。默认为 astro.config.mjs。如果使用了不同的配置文件名称或放在其他文件夹中，请使用：

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

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

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

启用完整日志，调试时有用。

启用静默日志，当你不想看到 Astro 日志时有用。

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

打印 Astro 版本号并退出。

在服务器启动时自动在浏览器中打开应用程序。

打印帮助信息并退出。