# @cloudhal/astro-renderer 中文文档

规范地址：https://npmcn.com/package/%40cloudhal/astro-renderer/

版本：0\.6\.5
npm 元数据更新时间：2026-11-08T22:23:10.477Z
中文译文更新时间：2026-11-10T03:37:15.093Z
软件包许可：Apache-2\.0

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

原始 npm 页面：https://www.npmjs.com/package/%40cloudhal/astro-renderer
原文对照：https://npmcn.com/package/%40cloudhal/astro-renderer/?lang=original
项目主页：https://cloudhal.dev/
源码仓库：https://github.com/cloudhal-dev/cloudhal

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

- 包体积（解压后）：939 kB，241 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：8 个
- peer 依赖：astro ^7\.4\.0，@astrojs/cloudflare ^14\.3\.0
- 首次发布：2026-10-20T10:50:14.604Z
- 最新版本发布：2026-11-08T22:23:10.147Z
- 近 30 天下载量：4403（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：26（近 12 个月 26 个）

## 中文简介

用 Astro 绘制一个 Cloudhal 站点图: 数据源(活/snapshot),段组件和 Cloudhal () 集成

## 安装

```sh
npm install @cloudhal/astro-renderer
```

也可以使用：`pnpm add @cloudhal/astro-renderer`、`yarn add @cloudhal/astro-renderer`、`bun add @cloudhal/astro-renderer`

## README

# @ cloudhal/ astro- reser

用Astro 7绘制出一个 Cloudhal 网站图 。 主要作品:

| 导出 | 什麽 |
| --- | --- |
| `@cloudhal/astro-renderer/integration` | `cloudhal({ dataDir, siteId })` ——曝光项目配置为: `virtual:cloudhal/config`,将本地的 SQLite 模块外部化,在dev 中监视数据目录,以便在添加页面时清除 Astro 的路由缓存(Astro \\ 6.3 缓存) `getStaticPaths()` (b) 对请求的处理. |
| `@cloudhal/astro-renderer/runtime` | `getSource(config)` a 包括: `GraphSource`数字 : **现场直播** dev( 可见草案) 中的节点, a **简介** 在建筑物中(`CLOUDHAL_SOURCE=snapshot:<id>`) (中文(简体) ). |
| `@cloudhal/astro-renderer/components` | `Sections` 调度器+ `Hero`, (中文(简体) ), `RichText`, (中文(简体) ), `Image`, (中文(简体) ), `ContentList` `.astro` 组件。 主题通过 `components` 道具 (英语). |
| `@cloudhal/astro-renderer/fields` | 已键入自定义字段(RFC-0041 第9段): `entryFields`, (中文(简体) ), `renderFields`, (中文(简体) ), `hasShownFields`,以及 `resolveFields`, (中文(简体) ), `formatFieldValue`, (中文(简体) ), `fieldLabel`, (中文(简体) ), `fieldHelp`, (中文(简体) ), `optionLabel` 从 `@cloudhal/core-ts/fields`。 。 。 . `EntryFields.astro` 内 `./components` 画出它们. |

启动器中的页面路由是这样的:

```astro
---
import { Sections } from "@cloudhal/astro-renderer/components";
import { getSource } from "@cloudhal/astro-renderer/runtime";
import config from "virtual:cloudhal/config";
export async function getStaticPaths() {
  const source = await getSource(config);
  return (await source.pages()).map((p) => ({ params: { path: p.path === "/" ? undefined : p.path.slice(1) } }));
}
const source = await getSource(config);
const page = await source.pageByPath(Astro.params.path ? `/${Astro.params.path}` : "/");
---
<Sections sections={page.sections} />
```

`.astro` 文件船作为源(没有构建步骤);消费者的Astro汇编它们. `astro` 是同级依赖.

## 主题化 API 稳定性

`cloudhal init` 副本 `starters/blog/src` 输入每个项目,所以一个站点会不断调用这个包的出口(和 `@cloudhal/core-ts`和创造时一样 每次导出一个主题进口因此都是公共的API:永远不要改变它同名的含义. 打破的改变使旧的呼唤保持了堕落倒地. 在0.3.11号文件中 `entryPath(entry)` 成为 `entryPath(site, entry)` 并且每个有更古老的主题副本的网站 都变成空页 直到0.3.13恢复它. `packages/cli/test/old-theme-compat.test.ts` 建立已冻结的较早启动的复制件(`packages/cli/test/fixtures/theme-v*/`)与今天的包裹. 当发行时更改了主题化的API时会添加一个新的被冻结的复制.

### 已打入自定义字段(RFC-0041,在0.5.0中加入)

添加剂; `entry.fields` 仍然代表着所储存的确切内容,以及从未像以前那样称为这些主题的渲染(`theme-v0.4.0` 在比较测试中.

| 导出 | 签署 |
| --- | --- |
| `GraphSource.entryFields?` | `(entry: ContentEntry, options?: EntryFieldsOptions) => Promise<RenderedFields>` 打开 `LiveSource` 财务报告和审定财务报表 `SnapshotSource` (在界面上选择,例如 `search?`(中文(简体) ) |
| `entryFields` (单位:千美元)`./fields`, (中文(简体) ), `.`(中文(简体) ) | `(source: FieldsSource, entry: ContentEntry, options?: EntryFieldsOptions) => Promise<RenderedFields>`: 对任何来源相同(`site()`选项 `entryById()` 财务报告和审定财务报表 `asset()`(中文(简体) ) |
| `renderFields` | `(resolved: ResolvedFields, options: RenderFieldsOptions) => RenderedFields`:纯粹的一步,因为你解决了自己的价值 |
| `hasShownFields` | `(fields: RenderedFields) => boolean` |
| `resolveFields`, (中文(简体) ), `formatFieldValue`, (中文(简体) ), `fieldLabel`, (中文(简体) ), `fieldHelp`, (中文(简体) ), `optionLabel` | 从 `@cloudhal/core-ts/fields` |
| `EntryFields` (单位:千美元)`./components`(中文(简体) ) | `<EntryFields fields={…} label?="Details" class?="…" />`(单位:千美元) `<dl class="ch-fields">` 的字段,当没有字段时无; 没有自己的样式 |

`EntryFieldsOptions`数字 : `locale` (默认:该条目的), `media` (这页) `MediaContext`, (中文(简体) ), `timeZone`, (中文(简体) ), `words` (单位:千美元)`{ yes, no }`, (中文(简体) ), `sizes`每一个 `RenderedField` 已经 `key`, (中文(简体) ), `label`, (中文(简体) ), `help?`, (中文(简体) ), `empty`, (中文(简体) ), `text` (逃避的纯正文本),和每类 `html` (丰富文本 通过身体的标记下降管道), `href` (单位:千美元)`safeHref`,在不安全时下降, `image` (单位:千美元)`imageAttributes` 加号 `assetId`,在页面的语言中备选案文)或 `datetime`附加时 `def`, (中文(简体) ), `value` 财务报告和审定财务报表 `fromOriginal` 从 `resolveFields`。主题指南: [`docs/guides/fields.md`](https://npmcn.com/package/docs/guides/fields.md)。 。 。 .

### 收集阶段3(RFC-0042,0.6.0中加入)

爱心. `entryHead`, (中文(简体) ), `entries()`, (中文(简体) ), `allEntries()` 而每个已存在的导出都保留其含义;旧的主题副本唯一产生的区别来自一个站点所选择的设置(`theme-v0.5.0` 在比对测试中:通过收藏的条目 `expiry` 保存列表、信息、网址图和搜索,以及 `contentList` 区域 `where`编号 :`orderBy` 按字段分列的列表(`ContentList.astro` 这里的船,并询问来源 一个主题的列表来自.

| 导出 | 签署 |
| --- | --- |
| `GraphSource.queryEntries?` | `(q: FieldEntryQuery) => Promise<FieldEntryResult>` 打开 `LiveSource` 财务报告和审定财务报表 `SnapshotSource`数字 : `{ collection, locale?, where?, orderBy?, sort?, filter?, limit? (1–100, default 20), offset?, includeExpired? }` → `{ entries, total }`· ; `now` 条件就是源头的瞬间 |
| `queryEntries` (单位:千美元)`./queries`, (中文(简体) ), `.`(中文(简体) ) | `(source: GraphSource, q: FieldEntryQuery) => Promise<FieldEntryResult>`: 任何来源(返回到 `entries()` 没有源 `queryEntries`; 一个无效的查询匹配无任何内容并正在登录 |
| `contentListEntries` (单位:千美元)`./queries`, (中文(简体) ), `.`(中文(简体) ) | `(source, sections, locale?) => Promise<Record<string, ContentEntry[]>>`页:1 `entries` 地图 `Sections` 读取(按收集;按编号 `filter` 用于 `where`编号 :`orderBy`(中文(简体) ) |
| `sectionQuery`, (中文(简体) ), `listsByField`, (中文(简体) ), `evaluateEntryQuery` (单位:千美元)`./queries`(中文(简体) ) | 查询区域运行; 是否按字段列出; 纯评价员共享两个来源 |
| `GraphSource.routableEntries?` | `(locale?) => Promise<ContentEntry[]>`:每个有公共URL的条目,包括未列出的条目(路线、静态构建、替代); `allEntries` 保留列出的 |
| `withStructuredData` (单位:千美元)`./seo`, (中文(简体) ), `.`(中文(简体) ) | `(head: HeadMeta, source, entry, { origin, media? }) => Promise<HeadMeta>`: 后调用 `entryHead`; 替换 `BlogPosting` 与收藏预设( )`Event`, (中文(简体) ), `JobPosting`, (中文(简体) ), `Product`, (中文(简体) ), `Recipe`当该条目具有所需要值时,保留该条目 `BreadcrumbList`返回 `head` 原文不变 |
| `entryStructuredData` (单位:千美元)`./seo`, (中文(简体) ), `.`(中文(简体) ) | `(source, entry, { origin, media? }) => Promise<{ doc?, issues }>`: 预设文档和为什么没有 |
| `collectionFeedLink` (单位:千美元)`./seo`, (中文(简体) ), `./collection-feeds`, (中文(简体) ), `.`(中文(简体) ) | `(site, collection, origin, locale?) => FeedLink | undefined`数字 : `{ title, href }` 收集的饲料`<prefix>/rss.xml`在当地居民的URL, `undefined` 与 `feed: false` 或无前缀的永久链接; 添加到 `head.feeds` 之后 `localizeHead` |
| `collectionFeedPath`, (中文(简体) ), `feedCollections`, (中文(简体) ), `collectionFeedPaths`, (中文(简体) ), `collectionForFeedPath` (单位:千美元)`./collection-feeds`(中文(简体) ) | 哪些收藏有饲料,在哪里; `staticPaths().feeds` 现在包括每个收藏种子路径 |
| `collectionFeedXml`, (中文(简体) ), `serveCollectionFeed` (单位:千美元)`./collection-feed-route`(中文(简体) ) | 集合的 RSS 在一个地方; 中间软件的决定( 一个主题的404 一个种子路径成为种子) |

收集种子: `cloudhal()` 集成后添加了中间软件(`collection-feed-middleware`目标 `<prefix>/rss.xml` (和 `/<locale><prefix>/rss.xml`)只有主题自己的路线回答404,所以主题自己的路线获胜而旧的拷贝获得种子;静态建筑通过起动器写入它们 `[...path]/rss.xml` 路径来自 `staticPaths().feeds`。规则和缓存标签与 `rss.xml`。 。 。 .

预览 : `renderSectionHtml(section, entries, media?, listing?)` 带 `{ site, now? }` 作为第四个论点 `renderPagePreview` 通过它,所以 `contentList` 区域 `where`编号 :`orderBy` 预览通过 `evaluateEntryQuery` 类似网站(一个术语) `filter` 仍然只在网站上适用).

指南 : [`docs/guides/structured-data.md`](https://npmcn.com/package/docs/guides/structured-data.md)。 。 。 .

衍生门: `unlist` 保留条目的页面(200),注释和菜单链接,但保留 `entries()`, (中文(简体) ), `allEntries()`, (中文(简体) ), `entriesByFilter`编号 :`entriesByTerm` (档案、相关)、资料、网址图和搜索; `hide` 404就像一个过期的 `availability`。两个源都应用它们,门索引在日期/日期列表字段的每个衍生瞬间和每个值瞬间封顶边缘缓存(用于 `now` 以“结束于...”通知”来忽略它们。 现场工人 `GET /__cloudhal/features` 答题 `{ "gates": 2 }`; 作者拒绝 `expiry` 直到它发生.

## 站点分析(RFC-0006)

渲染器搭载了Cloudhal的无饼干分析器(Cloudhal)的站点侧面(Cloudhal)`@cloudhal/analytics`:

-   **S文.** 现场工人建筑(`target: "cloudflare"`(b) 与《京都议定书》 `cloudhal()` 集成组合 `@cloudhal/analytics/client` 与Astro的Vite 分为两个散列静态资产, `/_cloudhal/p.<hash>.js` (页面视图脚本, ≤ 1 KB gzipped, 由测试进行)和 `/_cloudhal/v.<hash>.js` (维他命, `web-vitals`,以 N 中一个页面视图加载。 没有饼干,没有存储,没有识别器,没有第三方;CSP留下 `script-src 'self'; connect-src 'self'`。 。 。 .
-   **现场工人** (单位:千美元)`cloudflare-entry.ts`, (中文(简体) ), `analytics.ts`) (中文(简体) ). `POST /__cloudhal/e` 答题 `204` 目标`405` 用于其他方法),并将一个事件写入 `WaeWriter(env.ANALYTICS)`; 已出版的 HTML `200`开始吧 `<script type="module" src="/_cloudhal/p.<hash>.js" data-v="N">` 内 `<head>` 网站设置时( 从未预览、 出错或输入) ; 工作人生成的响应 `render` 事件( 已公布的 HTML `200`s,方向调整, `404`, (中文(简体) ), `410`, (中文(简体) ), `451`, (中文(简体) ), `5xx`) (中文(简体) ). 清洗会重新读取设置 .
-   **现场工人的期望** (书写人: `cloudhal deploy` 在推出步骤9中:分析引擎绑定 `ANALYTICS` (数据集) `<deployment>_events`, (中文(简体) ), `CLOUDHAL_ANALYTICS = "on"`, (中文(简体) ), `CLOUDHAL_ANALYTICS_DEFAULTS` (单位:千美元)`cloudhal.json`是因为 `analytics` 块为 JSON ; `enabled` 默认为 `true`),迁移 `0014_analytics` 在 D1 中(直到运行,分析计数为关闭),可选 `CLOUDHAL_SITE_HOSTS` (外部主机名称; `Site.domains` 财务报告和审定财务报表 `*.workers.dev` 请求主机已被接受). 没有开关或捆绑,则不收集任何信息,也不添加标签.
-   **`cloudhal dev`** (单位:千美元)`analytics-middleware.ts`, (中文(简体) ), `analytics-node.ts`) (中文(简体) ). 同一端点;它记录在本地的 SQLite 商店(`analytics_events`仅与 `analytics.dev: true` (一体化组织) `analytics` 选项,博客启动器从 `cloudhal.json`,或 `CLOUDHAL_ANALYTICS`, (中文(简体) ), `CLOUDHAL_ANALYTICS_DEFAULTS` 财务报告和审定财务报表 `CLOUDHAL_ANALYTICS_DEV=1` ),然后为脚本服务并注入标记. 静态建筑没有分析.

## 常见问题

### @cloudhal/astro-renderer 是什么？

用 Astro 绘制一个 Cloudhal 站点图: 数据源\(活/snapshot\),段组件和 Cloudhal \(\) 集成

### 如何安装 @cloudhal/astro-renderer？

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

### @cloudhal/astro-renderer 支持 TypeScript 吗？

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

### @cloudhal/astro-renderer 支持 ESM 还是 CommonJS？

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

### @cloudhal/astro-renderer 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @cloudhal/astro-renderer 可以商用吗？

@cloudhal/astro-renderer 使用 Apache-2\.0 许可。宽松许可：允许商业使用、修改和再分发，并附带明确的专利授权；分发时需保留许可与 NOTICE 文件，修改过的文件要注明改动。以上为概括，不构成法律意见，请以许可原文为准。

### @cloudhal/astro-renderer 的下载量有多少？

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

### @cloudhal/astro-renderer 还在维护吗？

最新版本 0\.6\.5 发布于 2026/11/09（1 天前）；至今共发布 26 个版本，其中过去 12 个月发布了 26 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。