# @distilled\.cloud/astro 中文文档

规范地址：https://npmcn.com/package/%40distilled.cloud/astro/

版本：0\.17\.1
npm 元数据更新时间：2026-09-10T19:24:59.106Z
中文译文更新时间：2026-11-12T12:33:06.834Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40distilled.cloud/astro
原文对照：https://npmcn.com/package/%40distilled.cloud/astro/?lang=original
项目主页：https://github.com/alchemy-run/cloudflare-tools/tree/main/packages/astro#readme
源码仓库：https://github.com/alchemy-run/cloudflare-tools

弃用说明：Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：380 kB，114 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：vite ^8\.0\.0，astro ^7\.0\.0，effect \>=4\.0\.0-beta\.102 \|\| \>=4\.0\.0，@effect/platform-bun \>=4\.0\.0-beta\.102 \|\| \>=4\.0\.0，@effect/platform-node \>=4\.0\.0-beta\.102 \|\| \>=4\.0\.0
- 首次发布：2026-08-06T07:00:17.558Z
- 最新版本发布：2026-08-06T08:04:40.590Z
- 近 30 天下载量：2932（2026-10-13 至 2026-11-11，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

执行框架-核心服务(建设/发展)的方案Astro集成,部署目标作为价值传递;将无摇篮的云浮工人目标(在@distilled.cloud/cloudflare-vite -- -- 上方的@astrojs/cloudflare分叉)运送至

## 安装

```sh
npm install @distilled.cloud/astro
```

也可以使用：`pnpm add @distilled.cloud/astro`、`yarn add @distilled.cloud/astro`、`bun add @distilled.cloud/astro`

## README

# @ distilled. cloud/ astro (英语)

程序化,无扳手的Astro集成.

此软件包执行框架核心 `Framework` astro 服务 - 效果 `build`编号 :`dev` astro公共方案 API(`import { build, dev } from "astro"`充满记忆 `AstroInlineConfig` (无) `astro.config.*`——并采用 **作为值部署目标**云层 工人目标(一叉) `@astrojs/cloudflare` 结束 `@distilled.cloud/cloudflare-vite-plugin`,没有扳手依赖和没有 `wrangler.json` (在任何地方) `./cloudflare` 子路径.

```ts
import * as Astro from "@distilled.cloud/astro";
import cloudflare from "@distilled.cloud/astro/cloudflare";

const layer = Astro.make({
  target: cloudflare({
    worker: {
      compatibilityDate: "2026-03-10",
      compatibilityFlags: ["nodejs_compat"],
      worker: {
        name: "my-app",
        bindings: [
          /* in-memory bindings */
        ],
      },
    },
  }),
  astro: { site: "https://example.com" },
});
// layer: Layer<Framework> — Framework.build → BuildOutput, Framework.dev → { url }
```

## 结构:框架一半x部署-目标一半

一揽子方案将两个关切问题分开(见 `packages/framework-core/README.md`, (中文(简体) ), "建筑:框架×部署目标",为完整的学说:

| 半数 | 模块 | 目录 |
| --- | --- | --- |
| **框架(平台中立)** | `src/index.ts`, (中文(简体) ), `src/Astro.ts`, (中文(简体) ), `src/Target.ts`, (中文(简体) ), `src/environments.ts` | 这个 `Framework` 服务执行:内置配置合成(`makeAstroInlineConfig`),方案 `build()`编号 :`dev()` 共享建设-产出收集器(`entryEnvironment: "ssr"`, (中文(简体) ), `skipEnvironments: ["astro", "prerender"]`),部署目标解析. **零云层进口** 由 `test/decoupling.test.ts`。 。 。 . |
| **云浮目标** | `src/cloudflare.ts` (传教士) `@distilled.cloud/astro/cloudflare`, (中文(简体) ), `src/integration.ts`, (中文(简体) ), `src/config-plugin.ts`, (中文(简体) ), `src/prerenderer.ts`, (中文(简体) ), `src/prerender-environment.ts`, (中文(简体) ), `src/prerender-middleware.ts`, (中文(简体) ), `src/runtime/**` | 这个 `AstroTarget` 工厂加一切 Cloudflare: 堡垒 `@astrojs/cloudflare` 在我们的vite插件、销售商的运行时间入口、 `virtual:astro-cloudflare:config` 插件, 工人预手( 建边驱动程序) `__astro_*` youtflare-runtime上的协议),dev节点前置中间软件插件. |
| **炼金术源提供者** | `src/source.ts` (传教士) `@distilled.cloud/astro/source`(中文(简体) ) | 炼金术 `Cloudflare.Workers` 源模块(结构 `SourceProvider` 镜像 : `build`编号 :`hash`编号 :`dev` 用于炼金工人资源。 Cloudflare在定义上具有特异性;直接构建Cloudflare目标. |

未来的平台(如AWS)是一个新的子路径,执行相同的 `AstroTarget` 组合——框架的一半或框架核心不变.

### 这个 `AstroTarget` 合同

`AstroTarget` 扩展框架核心的通用 `DeployTarget` 一个 特定框架钩:

```ts
interface AstroTarget<Config = unknown> extends DeployTarget<Config> {
  /** The Astro adapter integration pinned into AstroInlineConfig.adapter. */
  readonly integration: () => AstroIntegration;
}
```

所有特定平台都搭乘在集成内部(Astro的适配器) API 已经是右边的接合器: 它注入 vite 插件, 选择服务器 输入点,并配置构建)。 一般情况 `DeployTarget` 缝合是 受框架一半的约束:

-   `target.build` —— 说 **批发大楼收购**: 当定义时, `Framework.build` 代表整个生产建设到目标。 (云浮星盘) 目标不定义它——Astro驱动自己的构建. )
-   `finish` - 施工后结业通行证,通过 `applyDeployTargetFinish` 在收集器产生之后 `BuildOutput` (Astro的建筑是用记忆交付的,所以结尾上下文没有 打开磁盘 `entry`) (中文(简体) ).
-   `bundle` 解决/捆绑元数据(`conditions`, (中文(简体) ), `external`(b) 资料 用于Astro,因为集成会配置捆绑器本身.
-   `serve` - 当地服务 _已建成_ 输出; e2e 带的 Cloudflare 目标提供这个(最小值)。 不是HMR的dev路径.

### 如何通过目标

`Astro.make({ target, targetConfig })` 接受一个 `DeployTargetInput`数字 :

-   a 一个 `AstroTarget` **价值** ——用地(全型安全;自建 通过导入目标模块,
-   (单位:千美元) **工厂** `(config) => AstroTarget` 适用于 `targetConfig`, (中文(简体) ),
-   (单位:千美元) **模块指定符** 字符串——从 _项目的_ `node_modules` (数量) `default` -或名称 `target` - 出口是价值或工厂, 适用于 `targetConfig`。 。 。 .

选择 `target` 默认为 `"@distilled.cloud/astro/cloudflare"`这样 已有的 Cloudflare 用户不需要更改 。 目标解决一次 `build`编号 :`dev` 操作; 找不到已解决的目标 `integration` 钩子 键入失败 `FrameworkError`。 。 。 .

## 选项

### `Astro.make(options?: AstroFrameworkOptions)`

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `target` | `AstroTargetInput` | 部署目标(价值/工厂/规格)。 默认 : `"@distilled.cloud/astro/cloudflare"`。 。 。 . |
| `targetConfig` | `unknown` | 配置交给目标工厂/指定装入的模块. 不透明到框架的一半。 未使用时 `target` 是一个值. |
| `astro` | `AstroInlineConfig` | 额外 Astro 配置合并为内置内置配置( A)`site`, (中文(简体) ), `base`, (中文(简体) ), `redirects`, (中文(简体) ), `integrations`, (中文(简体) ), `devToolbar`, (中文(简体) ), `vite`(中文(简体) ). `root`, (中文(简体) ), `configFile: false`,以及 `adapter` 被钉住; `output` 默认为 `"server"`。 。 。 . |
| `root` | `string` | 项目根. 默认为 `process.cwd()`。 。 。 . |

### Cloudflare 目标配置`cloudflare(config)`(中文(简体) )

| 选项 | 类型 | 说明 |
| --- | --- | --- |
| `worker` | `CloudflareVitePluginOptions` | 兼容性日期/旗帜、工人名称/约束/资产行为、运行时背景——一切a `wrangler.json` 本来会带着的,记忆. `main`, (中文(简体) ), `viteEnvironments`Astro的节点环境 `skipEnvironments` 由整合管理. |
| `sessionKVBindingName` | `string` | 用于零配置会话的 KV 绑定名称, 在 Worker env 上显示时注入 Astro 的会话配置 。 默认 `"SESSION"`。 。 。 . |
| `sessions` | `boolean` | 零配置会话( 默认) `true`: 无时 `session.driver` 已经配置, Astro 的 `cloudflareKVBinding` 驱动程序配置 `sessionKVBindingName`。 。 。 . `false` 使会话配置不受影响. |
| `sessionDevKV` | `boolean` | 在 dev 中, 自动输入一个内嵌的本地 KV 命名空间( E)`KvNamespace.local`对会议具有约束力(默认) `true`) (中文(简体) ). 当dev 工人绑定时会禁用已发送带有该名称的 KV 绑定——绑定名称必须是独一无二的. |

上游 `@astrojs/cloudflare` 此分叉的适配选项 **没有** 支助 (单位:千美元)`imageService`, (中文(简体) ), `imagesBindingName`, (中文(简体) ), `platformProxy`, (中文(简体) ), `configPath`, (中文(简体) ), `persistState`, (中文(简体) ), `auxiliaryWorkers`, (中文(简体) ), `inspectorPort`, (中文(简体) ), `viteEnvironment`, (中文(简体) ), `cloudflareModules`, (中文(简体) ), `experimental`以明显的错误拒绝 被默默地忽略——每个错误都指代原因和迁移.

### E2e-机能使用量

默认导出是牵引框架工厂. 它读取了绳子 云层工人结构选择 (单位:千美元)`options.target?.cloudflare?.worker ?? options.vite`)并把它们作为 默认目标配置 :

```ts
// e2e.config.ts — untyped carriage
export default Options.make({
  target: { cloudflare: { worker: { /* ... */ }, preview: { /* miniflare */ } } },
  framework: "@distilled.cloud/astro",
});

// e2e.config.ts — typed target value (recommended; see fixtures/astro)
framework: (options) =>
  Astro.make({
    target: cloudflare({ worker: Options.resolveCloudflareOptions(options).worker }),
    astro: { devToolbar: { enabled: false } },
  }),
```

## 云旗目标会做什么

整合是一个叉子 `@astrojs/cloudflare` v14.1.3 (上游地区) 以 `@cloudflare/vite-plugin` + 扳手对等依赖,重修为 {\\fn黑体\\fs22\\bord1\\shad0\\3ahbe\\4ah00\\fscx67\\fscy66\\2chffffff\\3ch808080}是免费的 `@distilled.cloud/cloudflare-vite-plugin`数字 :

-   **交换插件 .** `@cloudflare/vite-plugin` 我们的插件, `main` 被钉住 供应商服务器入口(`@distilled.cloud/astro/entrypoints/server`, (中文(简体) ), 工人环境 `ssr`Astro的节点 `astro`编号 :`prerender` 环境 内 `skipEnvironments`Dev SSR通过Vite模块在工人内部执行 带有内存绑定的线条 `env.ASSETS` 404/资产倒置是 满足于运行时间的 vite-aware 资产回转(`Assets.local`) (中文(简体) ).
-   **弃去.** `loadWranglerEnv` + 键 `.dev.vars`,wrangler -config文件监视器, 页:1 `previewEntrypoint` (我们的运行时间为建设产出服务) 产出 -`wrangler.json` 补丁.
-   **工人先发制人(违约,如上游).** `prerenderEnvironment: "workerd"` 构建 `prerender` 环境状况 工人(与 `ssr` 并且从工人那里为它服务,d 通过 `cloudflare-runtime` ——没有Vite预览服务器,没有wrangler——同时 上游驱动器 `__astro_*` 对它执行 HTTP 协议 (单位:千美元)`src/prerenderer.ts`) (中文(简体) ). 制作运行时间的预发页面 : 顶级 `cloudflare:workers` 进口和配置的工人捆绑 工作的时间. `prerenderEnvironment: "node"` 倒计时 Astro 的股票节点预置器( + dev 节点预置器) 插件),用于构建时需要仅节点API的页面.
-   **铁丝网.** 这个 `passthrough` 图像服务(参见限制).
-   **取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取取.** 运行时间进入点/ 手动/ 帮助( 验证为免费) 缩写`@cloudflare/vite-plugin` 进口——由“复仇者”执行 运行时间纯度测试) `virtual:astro-cloudflare:config` 插件( 非) 导出于上游) `optimizeDeps.include` 环境插件 `cf-imports`编号 :`cf-externals` 插件,以及 `astro:build:setup` 服务器 微调( t)`ssr.noExternal`, (中文(简体) ), `sharp` 外部,进程-env横幅).
-   **固定(建设-产出均等).** 这个 `astro:build:done` 通过镜像 上游: `_redirects` 由 Astro 重定向路由生成( 配置) `redirects` + 重定向路由文件,通过 `@astrojs/underscore-redirects`这样 静态/前置重定向由资产层在 劳动者; `_headers` 获得不可改变的 `Cache-Control: public, max-age=31536000, immutable` 散列的规则 `_astro/` 资产目录( 当用户在 `_headers` 已经设置 匹配规则的缓存控制, 或是何时 `build.assetsPrefix` 积分资产 (b) 在另一来源; `injectTypes` 安装 `App.Locals` 运行时间类型 (单位:千美元)`@distilled.cloud/astro/types.d.ts`) (中文(简体) ).
-   **保留( P)`base !== "/"`) (中文(简体) ).** 客户端在基地下面筑巢 资产目录服务于 URL 根, 特殊文件 (单位:千美元)`.assetsignore`编号 :`_headers`编号 :`_redirects`)被移回上,并且 目标 `finish` 过分 `BuildOutput.clientDirectory` 回到过去 原始目录( 上游排放的当量) (原始内容存档于2018-09-26). wrangler.json `assets.directory` 补丁).
-   **会话( 0- 配置) .** 上游镜像: 没有配置 `session.driver`阿斯特罗的 `cloudflareKVBinding` 已配置驱动程序 反对: `sessionKVBindingName` 装订( a)`SESSION`; 供应商 运行时处理器从每个管道的工人内装入活的 KV 请求。 在Dev,一个记忆 `KvNamespace.local` 命名空间是自动添加的 对工人的束缚 `Astro.session` 零设置工作( 损坏) 通过 `sessionDevKV: false` 当你的编织物已经携带 (b) 约束。 在生产过程中,工人必须使用名为KV的装订装置 `sessionKVBindingName` (带有炼金术: 给工人一个 KV 命名空间) 绑定名称 `SESSION`) (中文(简体) ).
-   **`astro:env` 在建设时间.** 炼金术源提供者 (单位:千美元)`@distilled.cloud/astro/source`) 输入工人的字面内涵值 (弦声, `Redacted` 字符串、 数字/ 布尔等 `process.env` 在此之前 `build`编号 :`dev`这样 `astro:env` 配置加载时服务器机密解析并 节点先发制人——上游角色 `loadWranglerEnv` (叫声) `vars`
    -   `.dev.vars`) 剧作.
-   **Typegen后卫.** `build`编号 :`sync` 运行 Astro 的型号代号, 哪个靴子 a 临时 vite 服务器; 集成条 `configureServer` 从 云花板插件在这些阶段(在上游迷雾),所以从不工作 靴子中建——我们的干燥环境退化为可跑的根茎,a 支持dev插件的合同 .

### 构建输出

`Framework.build` 返回时 `BuildOutput` 合同内容: `serverModules` (首先进入—— `ssr` 条目块 `server/entry.mjs`, (中文(简体) ), 重新从磁盘读取,因为 Astro 输入了序列化的 SSR 显示于 捆绑完成)和 `clientDirectory` (单位:千美元)`dist/client`被俘虏的路 预发 HTML 在 vite 构建 骑行之后写成 - 包括 生成 `_redirects` 财务报告和审定财务报表 `_headers` 文档). 没有 `wrangler.json`,没有 `.wrangler/` 目录,任何地方.

## 限制

-   **节点前倒置会失去工人API.** 与 `prerenderEnvironment: "node"`,预留路线 (单位:千美元)`export const prerender = true`在Astro的股票中执行 **节点** ưμ㼯a `cloudflare:workers` (或其他情况) 依靠工人独占的API)在事前交接时间将无法在事前交接. 默认 `"workerd"` 模式没有此空格 – 预调运行在 工人使用附着的工人捆绑物.
-   **图像服务是传递.** 工人不能运行锐利 `IMAGES` 绑定在我们的运行时间中是远程的,所以集成硬线Astro的 `passthrough` 图像服务: 图像作为- is 服务( 没有调整大小 /) 格式谈判)。 生产终点是卖家 `image-passthrough-endpoint`; dev使用Astro的通用节点终点.
-   **会话需要在生产中装入已部署的 KV 绑定.** 零配置会话 在 Dev (模拟本地 KV) 中工作并配置已建的应用程序 读取 `sessionKVBindingName` KV 装订自工人舱内,但 提供已部署的工人的KV命名空间是部署 工具的工作。 没有它,会话操作在运行时间会失败.
-   **`astro preview` 未使用.** 上游预览硬接点 。服务构建的输出是部署目标的 `serve` 关注(e2e带中的最小值;炼金术 dev环路用途) 云浮-运行时间.
-   **版本针入.** Astro的JS API是: Astro的JS API是: `@experimental`和一体化 内部(虚拟模块名称、适配器特性)采用Astro版本 专业。 分叉轨道 `astro` 7.x /适配器 v14.1.3; 处理版本起伏 由固定的e2e套房作为后盾.

## 测试

-   `bun run test` - 单位测试(`test/Astro.test.ts`: 目标模块,配置 合成、集成接钩、批发-建设授权; `test/parity.test.ts`: 届会, `_redirects`编号 :`_headers` 世代相传, `base !== "/"` 处理, `injectTypes`,不支持选项的守护者,内 供餐; `test/decoupling.test.ts`:框架的一半无云层 保证和运行时间纯洁.
-   `fixtures/astro` - 剧作家e2e套房 驾驶一个真正的应用程序通过 双向带 `dev` (工人舱驾驶员)和 `live` (轻而易举) 已建出输出)模式: SSR + 绑定,中件本地/标题,配置 重定向(从生成的 `_redirects` 在直播模式下, `Astro.session` 往返,永久资产 `Cache-Control`JSON/二进制 终点、内容收藏、预发页、公共资产、ASSETS 404倒计时. (单位:千美元) A 类 `base !== "/"` fixture app还不是套房的一部分—— 行为经过单位测试 `test/parity.test.ts`. ) (中文(简体) )

## 常见问题

### @distilled\.cloud/astro 是什么？

执行框架-核心服务\(建设/发展\)的方案Astro集成,部署目标作为价值传递;将无摇篮的云浮工人目标\(在@distilled\.cloud/cloudflare-vite -- -- 上方的@astrojs/cloudflare分叉\)运送至注意：该包已被作者标记为弃用——Package no longer supported\. Contact Support at https://www\.npmjs\.com/support for more info\.

### 如何安装 @distilled\.cloud/astro？

在项目目录运行 npm install @distilled\.cloud/astro，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：vite（^8\.0\.0）、astro（^7\.0\.0）、effect（\>=4\.0\.0-beta\.102 \|\| \>=4\.0\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @distilled\.cloud/astro 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @distilled\.cloud/astro 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @distilled\.cloud/astro 可以商用吗？

@distilled\.cloud/astro 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @distilled\.cloud/astro 的下载量有多少？

根据 npm 官方下载统计，@distilled\.cloud/astro 在 2026/10/13 – 2026/11/11 这 30 天内被下载 2,932 次，日均约 98 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @distilled\.cloud/astro 还在维护吗？

最新版本 0\.17\.1 发布于 2026/08/06（3 个月前）；至今共发布 2 个版本，其中过去 12 个月发布了 2 个；首次发布于 2026/08/06。作者已将其标记为弃用，新项目建议寻找替代方案。