编程式 Astro API (实验性)

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

这些 API 是实验性的，其 API 签名可能会发生变化。任何更新都将在 Astro 更新日志中提及，以下信息将始终显示最新的信息。

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（默认）或未设置，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",
});

// Stop the server if needed
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() 方法返回的值。

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

// Stop the server if needed
await previewServer.stop();

PreviewServer

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

host

类型： string

服务器监听连接的主机。

适配器可以不设置此字段。host 的值是特定于实现的。

port

类型： number

服务器监听连接的端口。

stop()

类型： Promise<void>

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

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

closed()

类型： Promise<void>

返回一个 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 配置合并到一个现有的、有效的 Astro 配置之上。

mergeConfig() 接受一个 Astro 配置对象和一个部分配置（任何有效的 Astro 配置选项集），并返回一个有效的 Astro 配置，该配置结合了两个值，规则如下：

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

import { mergeConfig } from "astro/config";

mergeConfig(
  {
    output: 'static',
    site: 'https://example.com',
    integrations: [partytown()],
    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',
    },
  }
);

// Result is equivalent to:
{
  output: 'server',
  site: 'https://example.com',
  base: '/astro',
  integrations: [partytown(), 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: [partytown()],
}, "./my-project", "build");

// defaults are applied
await rm(config.outDir, { recursive: true, force: true });