编程式 Astro API（实验性）

如果你在运行 Astro 时需要进行更多的控制，可以使用 "astro" 包导出的 API 以编程方式运行 CLI 命令。

这些 API 是实验性的，其 API 签名可能会更改。任何更新都会在 Astro changelog 中提及，下面的信息将始终显示最新的信息。

`AstroInlineConfig`

AstroInlineConfig 类型由以下的所有命令 API 使用。它继承自用户的 Astro 配置类型：

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

`configFile`

类型： string | false
默认值： undefined

Astro 配置文件的自定义路径。

如果这个值为 undefined（默认值）或 unset，那么 Astro 将尝试搜索一个相对 root 目录的 astro.config.(js,mjs,ts,mts) 文件，如果找到的话，则加载配置文件。

如果设置了相对路径，它将根据 root 选项进行解析。

设置为 false 将禁用加载任何配置文件。

当与加载的用户配置并行时，此对象中传递的内联配置将具有最高优先级。

`mode`

类型： string
默认值： 运行 astro dev 时为 "development"，运行 astro build 时为 "production"

添加于： astro@5.0.0

开发或构建网站时使用的模式（例如，"production"，"testing"）。

当运行 astro build 或 astro dev 命令时，这个值会使用 --mode 标志传递给 Vite，以确定 import.meta.env.MODE 的值。这也决定了加载哪些 .env 文件，从而决定了 astro：env 的值。有关更多详细信息，请参阅环境变量页面。

要输出基于开发的构建，你可以使用 --devOutput 标志运行 astro build。

`logLevel`

类型： "debug" | "info" | "warn" | "error" | "silent"
默认值： "info"

用于过滤 Astro 所记录的消息的日志记录级别。

"debug"：记录所有内容，包括嘈杂的调试诊断。
"info"：记录信息性消息、警告和错误。
"warn"：记录警告和错误。
"error"：仅记录错误。
"silent"：无日志记录。

`dev()`

类型： (inlineConfig: AstroInlineConfig) => Promise<DevServer>

与 astro dev 相似，用于运行 Astro 的开发服务器。

import { dev } from "astro";

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

// 如需停止服务器：
await devServer.stop();

`DevServer`

export interface DevServer {
  address: AddressInfo;
  handle: (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void;
  watcher: vite.FSWatcher;
  stop(): Promise<void>;
}

`address`

类型： AddressInfo

开发服务器正在监听的地址。

此属性包含 Node 的 [net.Server#address() 方法]（https://nodejs.org/api/net.html#serveraddress）。

`handle()`

类型： (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => void

原始 Node HTTP 请求的句柄。你可以用 http.IncomingMessage 和 http.ServerResponse 来调用 handle()，而不是通过网络发送请求。

`watcher`

类型： vite.FSWatcher

Vite 的开发服务器暴露的 Chokidar 文件监视器。

`stop()`

类型： Promise<void>

停止开发服务器。这将关闭所有空闲连接并停止监听新连接。

返回一个 Promise，该 Promise 在完成所有待处理请求并关闭所有空闲连接后结束。

`build()`

类型： (inlineConfig: AstroInlineConfig) => Promise<void>

与 astro build 相似，用于构建你的站点以进行部署。

import { build } from "astro";

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

`preview()`

类型： (inlineConfig: AstroInlineConfig) => Promise<PreviewServer>

与 astro preview 相似，用于启动一个本地服务器来提供你的构建输出。

如果未在配置中设置适配器，则预览服务器将仅服务于构建中静态的文件。如果在配置中设置了适配器，则预览服务器将由适配器提供。适配器不需要提供预览服务器，因此该功能可能不可用，具体取决于你选择的适配器。

import { preview } from "astro";

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

// 如需停止服务器：
await previewServer.stop();

`PreviewServer`

export interface PreviewServer {
  host?: string;
  port: number;
  closed(): Promise<void>;
  stop(): Promise<void>;
}

`host`

类型： string

服务器所监听连接的 host。

允许适配器不设置此字段。host 的值通过特殊方式实现。

`port`

类型： number

服务器所监听连接的端口。

`stop()`

类型： Promise<void>

要求预览服务器关闭、停止接受请求并关闭空闲连接。

返回的 Promise 在发送关闭请求后解析。这并不意味着服务器已经关闭。如果需要确保服务器已完全关闭，请使用 closed() 方法。

`closed()`

类型： Promise<void>

返回一个 Promise，该 Promise 将在服务器关闭后结束，如果服务器上发生错误，则拒绝该 Promise。

`sync()`

类型： (inlineConfig: AstroInlineConfig) => Promise<void>

与 astro sync 相似，用于为所有的 Astro 模块生成 TypeScript 类型。

import { sync } from "astro";

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

贡献社区赞助