编程式 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, options?: BuildOptions) => Promise<void>

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

import { build } from "astro";

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

`BuildOptions`

export interface BuildOptions {
  devOutput?: boolean;
  teardownCompiler?: boolean;
}

`devOutput`

类型： boolean
默认值： false

添加于： astro@5.4.0 新

输出一个基于开发的构建，与在 astro dev 中转换的代码相似。这对于测试仅构建时出现的问题非常有用，同时包含附加的调试信息。

`teardownCompiler`

类型： boolean
默认值： true

添加于： astro@5.4.0 新

在构建完成后销毁编译器的 WASM 实例。这可以在单次构建时提升性能，但在连续多次构建时可能导致性能下降。

在同一次执行中构建多个项目时（例如测试期间），禁用这个选项可以显著提升性能并降低峰值内存占用，但代价是持续内存占用会升高。

`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",
});

`mergeConfig()`

类型： <T extends AstroConfig | AstroInlineConfig>(config: T, overrides: DeepPartial<T>) => T

添加于： astro@5.4.0 新

从 astro/config 导入，用于在现有有效的 Astro 配置基础上合并部分配置。

mergeConfig() 接受一个完整的 Astro 配置对象和一个部分配置（任意有效的 Astro 配置选项的集合），返回合并后的有效 Astro 配置。合并规则如下：

数组会被连接（包括集成和 remark 插件）。
对象会递归合并。
Vite 选项使用 Vite 自身的 mergeConfig 函数进行合并，默认启用 isRoot 标志。
可以作为函数提供的选项会被包装成新函数，这些新函数递归合并两个配置的返回值，遵循相同的规则。
其他所有选项会覆盖原有配置。

import { mergeConfig } from "astro/config";

mergeConfig(
  {
    output: 'static',
    site: 'https://example.com',
    integrations: [tailwind()],
    server: ({command}) => ({
      port: command === 'dev' ? 4321 : 1234,
    }),
    build: {
      client: './custom-client',
    },
  },
  {
    output: 'server',
    base: '/astro',
    integrations: [mdx()],
    server: ({command}) => ({
      host: command === 'dev' ? 'localhost' : 'site.localhost',
    }),
    build: {
      server: './custom-server',
    },
  }
);

// 合并后的结果等价于：
{
  output: 'server',
  site: 'https://example.com',
  base: '/astro',
  integrations: [tailwind(), mdx()],
  server: ({command}) => ({
    port: command === 'dev' ? 4321 : 1234,
    host: command === 'dev' ? 'localhost' : 'site.localhost',
  }),
  build: {
    client: './custom-client',
    server: './custom-server',
  },
}

`validateConfig()`

类型： (userConfig: any, root: string, cmd: string): Promise<AstroConfig>

添加于： astro@5.4.0 新

从 astro/config 导入，用于验证一个对象，就好像该对象是从 astro.config.mjs 导出并由 Astro 导入的一样。

接收以下参数：

待验证的配置
项目根目录
正在执行的 Astro 命令（build, dev, sync 等）

返回的 Promise 会解析为验证后的配置，包含适用于给定 Astro 命令的所有默认值。

import { validateConfig } from "astro/config";

const config = await validateConfig({
  integrations: [tailwind()],
}, "./my-project", "build");

// 已应用默认值
await rm(config.outDir, { recursive: true, force: true });

贡献社区赞助