# @cloudconfig/core 中文文档

规范地址：https://npmcn.com/package/%40cloudconfig/core/

版本：0\.4\.0
npm 元数据更新时间：2026-11-05T12:06:26.703Z
中文译文更新时间：2026-11-10T05:07:14.453Z
软件包许可：MIT

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

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

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

- 包体积（解压后）：1.2 MB，172 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.12\.0
- 运行依赖：19 个
- peer 依赖：agents 0\.27\.0，workflow 5\.2\.2，better-auth ^1\.7\.7，better-sqlite3 \*，@azure/functions ^4\.16\.5，durable-functions 3\.6\.0，@azure/storage-blob ^12\.34\.0，@better-auth/passkey ^1\.7\.7
- 首次发布：2026-09-18T06:40:22.017Z
- 最新版本发布：2026-11-05T12:06:26.506Z
- 近 30 天下载量：2064（2026-10-10 至 2026-11-08，npm 官方下载统计）
- 已发布版本数：13（近 12 个月 13 个）

## 中文简介

一个配置文件 — 一个部署在 Cloudflare, Vercel 或 Azure 上的后端. 数据库 登录 REST API 和一个来自单云.config.ts的打入客户端.

## 安装

```sh
npm install @cloudconfig/core
```

也可以使用：`pnpm add @cloudconfig/core`、`yarn add @cloudconfig/core`、`bun add @cloudconfig/core`

## README

# @ cloudconfig/ core (中文(简体) )

`@cloudconfig/core` 提供 CloudConfig 配置 API,服务器运行时间, 已键入客户端、数据库驱动程序、 MCP 服务器以及 `cloudconfig` 命令.

CloudConfig 将一个类型Script配置转换成 Cloudflare, Vercel 或 Azure 上的后端: a 数据库、迁移、验证的 REST 路径、访问规则、登录、输入、输入 客户端 和部署.

> CloudConfig 0.2 可用在地图上 `latest` npm dist-tag. (英语).

## 创建本地 API

你需要22.12节节点或更新:

```bash
pnpm dlx @cloudconfig/core@latest init blog-api --target standalone
cd blog-api
pnpm install
pnpm db:generate
pnpm db:migrate
pnpm dev
```

打开 `http://localhost:3000/api/_docs` 来探索生成的 API.

引用是一个自成一体的 HTML 页面,它跟随您的系统的光或者 黑暗主题 。 模型 API 的 OpenAPI 3. 1 文档在 `http://localhost:3000/api/openapi.json`; 将其导入 Swagger UI、 Postman 或 a 客户端生成器。 两个URL都跟随 `server.basePath` 并因 `server.docs: false`。 。 。 .

规格包括模型输入、响应计划、平面图、过滤器、, 还有错误 写入有效载荷使用关系ID;答复包含嵌入关系 对象。 PUT和PACH都进行部分更新. 更好的认证端点和 自定义应用程序路由是独立的API,不包含在本导出中.

对于未启动服务器的导出, 请使用 `buildOpenApiDocument(compileConfig(config))` 从 `@cloudconfig/core/server`。 。 。 .

## 定义模型

```ts
import { defineBackend, model, t } from '@cloudconfig/core'

export const config = defineBackend({
  models: {
    post: model(
      {
        title: t.text().required(),
        body: t.textarea(),
        published: t.boolean().default(false),
      },
      {
        access: {
          list: ({ where }) => where('published', 'eq', true),
        },
      },
    ),
  },
})
```

CloudConfig在数据库计划,迁移,验证, REST路由,打入客户端,API文档,以及MCP工具.

## 使用输入客户端

```ts
import { createClient } from '@cloudconfig/core/client'
import type { config } from './cloud.config'

const api = createClient<typeof config>({
  baseUrl: 'http://localhost:3000/api',
})

const posts = await api.post.list({ page: 1, pageSize: 20 })
```

## 存储代理定义

特工是选入的核心能力 将内置模型组成您的配置 :

```ts
import { defineBackend } from '@cloudconfig/core'
import { agentModels } from '@cloudconfig/core/agents'

export const config = defineBackend({ models: { ...agentModels } })
```

生成并应用迁移, 然后使用 `api.agent` 从输入的客户端. 每个定义存储Markdown指令,一个提供者和模型ID,草稿/活性 状态、工具选择和工具声明. `runtime` 选择 `api`, (中文(简体) ), `codex`,或 `claude`· ; `localModel` 独立于 API 模型,默认为 CLI 默认。 主机执行CLI执行,部署时使用API提供者/模型. 进入范围为注册所有人; 钩子从第一个"Markdown"所有权中取出名称并强制执行所有权.

`createAgentDefinition(name)` 范围、界限、决策和 工具使用模板. `serializeAgentMarkdown` 财务报告和审定财务报表 `parseAgentMarkdown` 保护 在 Markdown 前题中设置和完整的工具声明. `agentToolSchema` 导出 OpenAI 响应、 Anthropic 或 Google 声明; 它不执行 工具。 主机提供供应商证书,工具处理器和执行.

## 部署代理人和自动化

Nuxt 项目可以声明 `deploy.agent` 财务报告和审定财务报表 `deploy.automations` 在他们的配置. CloudConfig 选择 Cloudflare 持久对象和提醒、 Vercel 工作流程或 a 将 Azure 持久函数应用程序与私人 Blob 执行状态分开. 自动化任务支持持续 检查站,时间表,延误,事件等待, 并取消。 连接可以将已验证的 Webhooks 交给持久任务并运行 预定的代号刷新和加密密钥维护.

Vercel 默认为已存在的 Turso 数据库; Cloudflare 默认为 D1. 选择 D1,Turso,或libSQL明确保持数据库选择独立于应用程序托管. 在部署前提供选定的提供者的证书.

见 [部署人员](https://cloudconfig.dev/docs/deployment/agents), (中文(简体) ), [部署自动化](https://cloudconfig.dev/docs/deployment/automations),以及 [平台支持](https://cloudconfig.dev/docs/deployment/support) 运行时间 依赖性、储存地点和剩余限度.

## 以 Cloudflare 的 CLI (β) 部署

当项目有参考文献时 `cloudflare.config.ts` 和没有Wrangler配置, `cloudconfig deploy` 运行 `cf build`,飞行前并适用D1迁移,以及 将工人的秘密通过上传 `cf deploy --prebuilt`扩展 源自 `cloud.config.ts` 进入工人的环境:

```ts
// cloudflare.config.ts
import { defineConfig } from 'cf/config'
import { cloudflareBindings } from '@cloudconfig/core/cloudflare'
import config from './cloud.config.ts'

export default defineConfig({
  worker: {
    name: 'blog-api',
    compatibilityDate: '2026-10-14',
    entrypoint: './src/index.ts',
    env: { ...cloudflareBindings(config) },
  },
})
```

Nuxt 本地开发、代理、自动化、工作流程、Turnstile和远程 libSQL 仍然需要 `wrangler.jsonc`。见 [部署到云浮](https://cloudconfig.dev/docs/deployment/cloudflare#deploy-with-the-cf-cli-beta)。 。 。 .

## 生成 Void (审查) 的后端

CloudConfig 0.0.0 包括: 与麻省理工学院许可证相同的Void入境点 云相会. 此集成预览针对 Void 1.1.11, 需要 节点.js 24.210.0或更新.

保留 `cloud.config.ts` 作为模型、访问规则、认证和连接的来源. 衍生出Void的资源申报:

```ts
// void.config.ts
import { createVoidBackendConfig } from '@cloudconfig/core/void/config'
import { config } from './cloud.config'

export default createVoidBackendConfig(config, {
  name: 'my-void-backend',
  compatibilityDate: '2026-10-14',
})
```

生成 SQL 以 `cloudconfig db generate` 在开始Void之前。 然后准备 构建 Void 的 Vite 插件前的后端 :

```ts
// vite.config.ts
import { defineConfig } from 'vite'
import { voidPlugin } from 'void'
import { cloudconfigVoid } from '@cloudconfig/core/void/vite'

export default defineConfig({
  plugins: [await cloudconfigVoid(), voidPlugin()],
})
```

运行 `cloudconfig void prepare` 分别出口或检查这些文物. 保持"维特"帮手"本土发展身份和"工人"出口接线. 通过编译应用程序、认证和连接表准备导出 `db/schema.ts`,将权威 SQL 和 Drizzle 的快照镜像成 `db/migrations`中,通过 `env.ts`,以及 在下方生成本地 API 路由 `routes/` 时间 `server.basePath` (默认) `/api`) (中文(简体) ). 显形相 `sourceDir` 移动这些切入点与应用程序 路线和工作。 生成的执行保留在 `.cloudconfig/void/`。 。 。 . 既不打开数据库,也不提供资源,也不应用SQL. Void拥有这些步骤。 在模型改变后用 CloudConfig 重生 SQL; 生成的 Void 计划不是第二个迁移源.

Void的破坏性出行护卫仍然适用于入行历史. 核准 不编辑现有的 CloudConfig 分类账而审查历史 SQL, 导出 `cloudconfigApprovedDestructiveMigrations` 从 `void.config.ts` 作为 SQL 的地图 确切的SHA-256源码的文件名 准备加Void的 `-- void:allow-destructive` 仅在生成的镜像中注释。 已更改来源 字节失败准备; 未批准的文件保持不变 。 同样的地图可以是 以 `approvedDestructiveMigrations` 给 Vite 帮助者或准备 API. 这需要单独的镜像:共享权威的SQL从未被附加注释.

何时 `deploy.agent`, (中文(简体) ), `deploy.automations` 或者说 `deploy.workflows` 已配置, vite 帮助者还将生成的工人输出附加到 Void 的本地条目上. 它创建了 Cloudflare 代理和自动化适配器,并保留 Connect for 自动化执行, 注册代理平台, 以及名为 Workflow 的转发 课程。 这些声明必须存在的只引用服务器的条目文件 在准备之前。 准备 CLI 生成适配器模块, 但是 需要维特的帮助 这个钩子目前跟随Void 1.11的 生成 `.void/entry.ts`; SDK 更新需要符合性检查.

框架应用程序保留其现有的 CloudConfig 挂载: set `appType: 'framework'` 在配置助手中,或通过 `--framework` 准备. 它们的框架一体化继续拥有工人的出口. 帮助者正面标记本地开发请求 只针对Vite `serve` 命令。 构建和预览保留生产环境,包括: 发展身份提供者在发展之外通常拒绝. Vite 助手在配置评价时间准备文件; 它不监视 计划改变。 在再生成SQL后重新启动开发过程.

准备保护被撰写的文件和迁移目录. 如果你已经 保持权威迁移 `db/migrations`设置 `db.migrationsDir` 给那个 直接共享历史的路径。 保留现有的 `env.ts`,通过 `environment: 'external'` 转到 Vite 帮助器或运行 `cloudconfig void prepare --external-env`,然后编写生成的验证符 :

```ts
// env.ts
import { defineEnv, string } from 'void/env'
import { environmentSchema } from './.cloudconfig/void/env'

export default defineEnv({
  ...environmentSchema,
  APPLICATION_KEY: string(),
})
```

添加 `.cloudconfig/void/` 并生成切入点到 `.gitignore` 当他们是 设置时重建. 生成的环境文件包含可变名称 和验证规则,而不是秘密值。 通过 Void 上传所需值 部署前的秘密工作流程。 使用不同的资源名称进行评价; 准备不会从另一个部署中传输数据.

`createVoidBackend(config)` 从 `@cloudconfig/core/void/server` 也提供 为自定义挂载。 转发原始的 Web 请求并绑定到 `backend.fetch(request, env)`后端用途 `config.db.binding` (默认) `DB`(中文(简体) ) 并保留验证、访问规则、钩子、更好的Auth、连接、OpenAPI和 API参考.

使用 `createVoidServerClient(config, context)` 从同一切入点 在 Void 处理器或任务内输入服务器操作。 它的背景包括: 原始Web请求和平台绑定.

`createVoidTools(config, context)` 从 `@cloudconfig/core/void/tools` 生成 schema的工具定义,操作动作, JSON schemas, Zod schemas 和执行器. 执行者 返回时 `OpResult`,验证论据并使用公共操作边界, 因此,只使用服务器的字段不使用工具输入和结果。 供应 `getUser` 改为 使用主机身份提供者; 配置的 CloudConfig 认证块解决其 默认为自有会话。 该应用程序仍然拥有其模型提供者 审查/核准政策.

`createVoidMcpServer(config, options)` 从 `@cloudconfig/core/void/mcp` 曝光情况 相同的模型词汇通过MCP. 供应 `env` 装订D1 一种明确的认证模式。 需要网络运输 `getUser`; 已修正 匿名负责人仍限于当地交通工具。 工厂确实如此 不安装未经认证的 HTTP 端点 .

Nuxt Agentic 预览带一个版本绑定的 Void 补丁来保存工人 输出和现有事件处理者,创造本地工作,并允许明确 root Wrangler 配置与 Void 生成的文件并列 。 这些修正是: 仍然是上游贡献的候选者;这个适配器没有安装. 保留已存在的 CloudConfig root Wrangler 文件需要此补丁 `preserveWranglerConfig: true` 内 `createVoidBackendConfig`没有它,Void的 正常根 Wrangler 迁移要求仍然适用. 补丁也支持 `preserveEnvExample: true` 只保留文档 `.env.example`。该文件没有被装入;其他本地 dotenv 变体依然存在 受Void正常限制.

这些适配器有TypeScript覆盖. 模拟运行时间和部署符合规定 ;不要将预览视为一个全面的支持发布.

## 学习更多

-   [导言](https://cloudconfig.dev/docs)
-   [快速启动](https://cloudconfig.dev/docs/quickstart)
-   [要点](https://cloudconfig.dev/docs/configuration)
-   [纳克思融合](https://www.npmjs.com/package/@cloudconfig/nuxt)
-   [公共展示和发行跟踪器](https://github.com/dennisadriaans/cloudconfig)

执行工作由私人存放处负责。 公众 GitHub 存储器主机为产品概览和社区问题.

麻省理工学院.

## 常见问题

### @cloudconfig/core 是什么？

一个配置文件 — 一个部署在 Cloudflare, Vercel 或 Azure 上的后端\. 数据库 登录 REST API 和一个来自单云\.config\.ts的打入客户端\.

### 如何安装 @cloudconfig/core？

在项目目录运行 npm install @cloudconfig/core，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 cloudconfig，可以用 npx cloudconfig 直接运行。

### @cloudconfig/core 支持 TypeScript 吗？

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

### @cloudconfig/core 支持 ESM 还是 CommonJS？

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

### @cloudconfig/core 需要什么版本的 Node\.js？

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

### @cloudconfig/core 可以商用吗？

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

### @cloudconfig/core 的下载量有多少？

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

### @cloudconfig/core 还在维护吗？

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