# @bettercms-ai/astro 中文文档

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

版本：0\.33\.0
npm 元数据更新时间：2026-11-05T14:14:45.587Z
中文译文更新时间：2026-11-08T00:27:53.460Z
软件包许可：未声明

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

原始 npm 页面：https://www.npmjs.com/package/%40bettercms-ai/astro
原文对照：https://npmcn.com/package/%40bettercms-ai/astro/?lang=original

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

- 包体积（解压后）：278 kB，43 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：7 个
- peer 依赖：astro \>=4，@astrojs/preact \>=4
- 首次发布：2026-06-30T11:08:18.859Z
- 最新版本发布：2026-11-05T14:14:45.395Z
- 近 30 天下载量：4361（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：63（近 12 个月 63 个）

## 中文简介

Astro的更好的CMS适配器—— a `bettercms()` 一体化,a `bettercms:client` 虚拟模块,打入内容加载器,草稿预览,以及原生的.astro渲染组件.

## 安装

```sh
npm install @bettercms-ai/astro
```

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

## README

# 翻译:

Astro的更好的CMS适配器—— a `bettercms()` 一体化,a `bettercms:client` 虚拟模块、打入的内容加载器、预览草稿以及 本地语言 `.astro` 渲染组件。 等同天文仪 `@sanity/astro`。 。 。 .

## 安装

```bash
npm install @bettercms-ai/astro
```

## 设置

```js
// astro.config.mjs
import { defineConfig } from "astro/config";
import bettercms from "@bettercms-ai/astro";

export default defineConfig({
  integrations: [
    bettercms({
      apiUrl: "https://api.bettercms.ai", // or PUBLIC_BCMS_API_URL
      workspace: "my-workspace",          // or PUBLIC_BCMS_WORKSPACE
      // projectId, studioUrl, mediaUrl optional
    }),
  ],
  output: "server", // required for draft mode + live reads
});
```

### 环境变量

每个公共价值都以这个顺序决定: `bettercms({ ... })` 选项,然后输入,然后输入 `bcms-content.json` 在构建前快取部署工作流程 .

| 变量 | 选项 | 读取 | 默认/ 注释 |
| --- | --- | --- | --- |
| `PUBLIC_BCMS_API_URL` | `apiUrl` | 配置时间 | 需要( 选项、 隐藏或快照) |
| `PUBLIC_BCMS_WORKSPACE` | `workspace` | 配置时间 | 需要( 选项、 隐藏或快照) |
| `PUBLIC_BCMS_PROJECT_ID` | `projectId` | 配置时间 | 表格的可选项目范围 |
| `PUBLIC_BCMS_MEDIA_URL` | `mediaUrl` | 配置时间 | `https://cdn.bettercms.ai` |
| `PUBLIC_BCMS_STUDIO_URL` | `studioUrl` | 配置时间 | 未设. `<BcmsVisualEditing>` 倒计时 `https://bettercms.ai` |
| `BCMS_API_KEY` | 无 | 服务器运行时间 | `content:read`,或 `content:read:draft` 用于预览草稿。 从不捆绑 |
| `BCMS_DRAFT_SECRET` | 无 | 服务器运行时间 | 签署饼干草稿。 运行时间 `process.env` 胜过构建时间值。 没有它 `/api/bcms/draft/enable` 返回 500 |

BetterCMS生成的部署工作流程集 `PUBLIC_BCMS_API_URL`, (中文(简体) ), `PUBLIC_BCMS_WORKSPACE` 财务报告和审定财务报表 `PUBLIC_BCMS_PROJECT_ID` 为建筑。 它的回转秘密 `BCMS_API_KEY` 仅到达 内容- fatch step, 永远不要建. 在您的主机上, 自己设置两个服务器变量 .

此包裹船无再验证路线. 指出工程的再验证 Webhook (Project ~ 设置) 在您的重建钩。 它的秘密(保存于 `BCMS_REVALIDATE_SECRET`将身体标为 `x-bettercms-signature: sha256=<hmac>`。 。 。 .

添加虚拟模块 + `Astro.locals` 类型改为 `src/env.d.ts`数字 :

```ts
/// <reference types="@bettercms-ai/astro/env" />
```

## 阅读内容

```astro
---
import { loadPage, loadForms } from "bettercms:client";
import BcmsBlocks from "@bettercms-ai/astro/components/BcmsBlocks.astro";

const page = await loadPage(Astro, "home");
const { items: forms, turnstileSiteKey } = await loadForms(Astro);
---
{page && <BcmsBlocks blocks={page.blocks} forms={forms} turnstileSiteKey={turnstileSiteKey} />}
```

装入器 `Astro` 因此,当草稿模式打开时,它们会自动读取草稿: `loadPage`, (中文(简体) ), `loadEntry`, (中文(简体) ), `loadEntries`, (中文(简体) ), `loadForms`原始内容 `client` 财务报告和审定财务报表 `getClient(Astro)` 也输出.

## SEO——每页 `<head>`

`loadPage()` 返回页面 `metaTitle`, (中文(简体) ), `metaDescription`有钱人 `metaJson` (OG / Twitter / canonical / JSON-LD)在仪表板的SEO面板上编辑. 解决他们 页面翻页网站 `resolveSeo` 然后将结果映射到您 `<head>` (同样的优先) 作为活人 `*.bettercms.site` 渲染器 :

```astro
---
import { loadPage } from "bettercms:client";
import { resolveSeo, type SiteSeoDefaults } from "@bettercms-ai/astro";

const { slug } = Astro.params;
const page = await loadPage(Astro, slug ?? "home");

const siteDefaults: SiteSeoDefaults = {
  metaDescription: "Selected work, experience, and contact information.",
  ogImage: "https://example.com/og-default.png",
  twitterHandle: "@acme",
};

const seo = page ? resolveSeo(page, siteDefaults) : null;
---
{seo && (
  <Fragment slot="head">
    <title>{seo.title}</title>
    {seo.description && <meta name="description" content={seo.description} />}
    {seo.canonical && <link rel="canonical" href={seo.canonical} />}
    {seo.og.title && <meta property="og:title" content={seo.og.title} />}
    {seo.og.description && <meta property="og:description" content={seo.og.description} />}
    {seo.og.image && <meta property="og:image" content={seo.og.image} />}
    <meta property="og:type" content={seo.og.type} />
    <meta name="twitter:card" content={seo.twitter.card} />
    {seo.twitter.image && <meta name="twitter:image" content={seo.twitter.image} />}
    {seo.twitter.site && <meta name="twitter:site" content={seo.twitter.site} />}
    {seo.jsonLd.map((node) => (
      <script type="application/ld+json" set:html={JSON.stringify(node)} />
    ))}
  </Fragment>
)}
```

已读已缓存; 下次获取时会显示 SEO 编辑 。 出版时立即刷新, 配置工程的再验证 Webhook (Project ~ Sets) 与您的重建相对应 或按需复用钩.

## 构成部分

| 构成部分 | 目的 |
| --- | --- |
| `@bettercms-ai/astro/components/BcmsBlocks.astro` | 翻出一页 `blockJson` ——每个区块类型构建者可以写作(标题,文本/丰富文本,图像,按钮,空间器,视频,列,形式,区段,导航栏,页脚,滑块,标签,组件),并应用了区块样式符号. |
| `@bettercms-ai/astro/components/BcmsForm.astro` | Render + 提交一个表单(有条件的田地,蜜壶,特恩斯地. |
| `@bettercms-ai/astro/components/BcmsImage.astro` | 通过介质变换端点以 1x/2x srcset来优化图像. |
| `@bettercms-ai/astro/components/BcmsLiveBlocks.astro` | `BcmsBlocks` 作为水分岛 让Visual Editor重新将您的DraftS 与您自己的组件和 CSS 重交. 见下文. |

Markup是班级驱动的,没有风格——你拥有CSS.

### 带有国家代码拾取器的电话字段

作者启用的电话字段 **国家代码拾取器** 在建设者中使一个国家 控制在号码旁边 不管访客选什么 球场还是呈递 **一个值**, (中文(简体) ), e.164(在自己的密钥下)`+14155550123`)——没有第二把钥匙可以处理.

两个班是你的风格:

| 类 | 元素 |
| --- | --- |
| `bcms-phone` | 国家控制周围的包装和数字 |
| `bcms-phone-country` | 国家控制自己 |

国家管制是本地人 `<select>` 建造时间/ SSR 时间,所以 **没有电话库 到达访客浏览器**交易是,数字没有重新调整 已键入 —— 提交时,该数值仍然构成正确. `@bettercms-ai/next` 做另一个 {\\fn华文楷体\\fs20\\bord1\\shad1\\1che0e0e0\\2ch000000}再把活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活活.

## 内容管理系统顺序: `<BcmsSections>`

页面,其章节以 `.astro` 文件按照它的 CMS 页面排序 列出他们。 每个区块都放在一个命名的槽中, 以它的放置绑定来命名; 内部的标记是 汝所出而成正觉.

```astro
---
import BcmsSections from "@bettercms-ai/astro/components/BcmsSections.astro";
---
<Layout>
  <BcmsSections page="home">
    <Fragment slot="hero"><Hero /></Fragment>
    <Fragment slot="code:sec1"><LogoStrip /></Fragment>
    <Fragment slot="features"><Features /></Fragment>
  </BcmsSections>
</Layout>
```

-   一个被捆绑到一个位置的区块 使那个位置处于该位置 它的根元素会得到 `data-bcms-block`, (中文(简体) ), `data-bcms-style` 和块的样式;周围没有添加元素.
-   编辑器中添加的一节( 块无绑定) 由 `<BcmsBlocks>`,哪个 `<BcmsSections>` 进口本身。 它需要没有 `bettercms()` 基础:没有整合 组件改为 `PUBLIC_BCMS_*` 和内容快照. `Blocks` 在另一个渲染器里交换.
-   无块名的插槽 : `code:<bind>` 总是让你写的地方。 一个赤裸的 `<bind>` 也一样 ,直到列表名称页的某个槽;之后是已删除的段落.
-   由于没有快照(本地建筑, API倒下), 每个插槽都按源顺序排列, 不加更改 .

块列表是已公布的快照 (`bcms-content.json`),或者草案的当视觉 编辑器在草稿模式中设定服务器发送的页面 。 过 `blocks` 给它自己. `npx @bettercms-ai/convert --sections` 写这个包裹给你.

## 在静态网站上进行现场编辑—— `<BcmsLiveBlocks>`

当Visual 编辑器设定一个静态构建时,它只能显示所构建的东西,所以编辑一个 草稿回到月台的近似渲染器 画布也不再像你 网站. `<BcmsLiveBlocks>` 修正身体为块状树的页面: 标记 `<BcmsBlocks>` 是的,但作为一个 `client:load` 接受联合国文件草案的岛屿 编辑器结束 `postMessage` (同源出处,仅出自父框,仅出自编辑器本身) (掌声) 握手——第三方页面 iframed your site 是一个外国来源,却一无所获. 页面没有获取任何信息,也没有证书输入.

它需要一个 JSX 渲染器,一个组件不能为您添加:

```sh
npm i @astrojs/preact preact
```

```js
// astro.config.mjs
import preact from "@astrojs/preact";
export default defineConfig({ integrations: [bettercms(), preact({ compat: true })] });
```

```astro
---
import BcmsLiveBlocks from "@bettercms-ai/astro/components/BcmsLiveBlocks.astro";
const page = await getPage(Astro.params.slug);
const { forms } = await readForms();
---
<BcmsLiveBlocks slug={page.slug} blocks={page.blocks} forms={forms} />
```

`compat: true` 需要——岛屿再利用反应 `<BcmsDraftBridge>` 从 `@bettercms-ai/next` 所以两个SDK都说一个协议 大约10 kB 预告加块 出纳器; `@astrojs/react` 如果您的项目已经使用过, 也会工作 .

⚠️ **它释放出反应类的名称,而不是这个包的.** `<BcmsBlocks>` 从 [`@bettercms-ai/next`](https://www.npmjs.com/package/@bettercms-ai/next) 分类其输出 `bcms-block bcms-block--text`, (中文(简体) ), `bcms-button--primary`, (中文(简体) ), `bcms-column`· ; `BcmsBlocks.astro` 上文 类同树 `bcms-text`, (中文(简体) ), `bcms-btn-primary`, (中文(简体) ), `bcms-cols`。它们不可互换:a 样式表为 `.astro` 这岛上没有文法风格 所以换一页 没有风格。 将两种拼法都覆盖起来——开始者将它们包成一 `:is()` 精确选择此选项 理由——或从 `@bettercms-ai/next`是因为 `src/blocks.tsx`。 。 。 .

**只会帮助你翻出页面 `BcmsBlocks`。 。 。 .** 手写 `.astro` 版式,或 内容被拉入你自己的组件,对于桥梁来说是看不见的——对于那些,结构上的 草稿预览需要服务器的草稿路由代替(`output: 'server'` + 模式草案 (以下各条路线).

## 草稿模式

融合注入 `/api/bcms/draft/enable?token=<jwt>&redirect=/path` 财务报告和审定财务报表 `/api/bcms/draft/disable`从仪表板上生成预览式链接; 来访 `enable` 对后端验证指使 设置一个签名的饼干, 和后续加载返回草稿内容。 与 `disable` 路线.

### 两道车道

| 莱恩 | 构建 | 画布如何显示草稿 |
| --- | --- | --- |
| 安全部门改革 | `output: "server"` +以上航道草案 + `BCMS_DRAFT_SECRET` +a 键 `content:read:draft` `BCMS_API_KEY` | 装填器在每次请求时都会阅读草稿,所以手写布局也会预览 |
| 静态 | 任何静态的构造, 与页体通过 `<BcmsLiveBlocks>` | 编辑们把草块树推到岛上 `postMessage`。没有获取,没有页面中的密钥。 只有 `BcmsLiveBlocks` 区域最新情况 |

## 无头项目(你自己的主办方)

BetterCMS从不构建,发布或部署无头项目. 任何建筑、文物或部署 请求返回一次 **409个 `HEADLESS_NO_BUILD`**。 。 。 .

-   **部署:** 推到你的仓库。 您的提供者( Vercel、 Netlify 或 Cloudflare 页面) 建造它。 对于发布时的新内容,请将重新验证的网页点击提供者 重建钩子.
-   **草案:** 使用您框架的草稿路由在提供者的 **预览** 部署 URL. 对于Astro,即上面的SSR道: `output: "server"`,输入 `/api/bcms/draft/*` 路线, `BCMS_DRAFT_SECRET`,则a `BCMS_API_KEY` 携带 `content:read:draft`. 将密钥草稿停产.

## 常见问题

### @bettercms-ai/astro 是什么？

Astro的更好的CMS适配器—— a bettercms\(\) 一体化,a bettercms:client 虚拟模块,打入内容加载器,草稿预览,以及原生的\.astro渲染组件\.

### 如何安装 @bettercms-ai/astro？

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

### @bettercms-ai/astro 支持 TypeScript 吗？

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

### @bettercms-ai/astro 支持 ESM 还是 CommonJS？

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

### @bettercms-ai/astro 可以商用吗？

@bettercms-ai/astro 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @bettercms-ai/astro 的下载量有多少？

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

### @bettercms-ai/astro 还在维护吗？

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