# @cosmicjs/sdk 中文文档 规范地址：https://npmcn.com/package/%40cosmicjs/sdk/ 版本：2\.4\.0 npm 元数据更新时间：2026-09-09T18:10:38.354Z 中文译文更新时间：2026-11-10T20:14:22.259Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cosmicjs/sdk 原文对照：https://npmcn.com/package/%40cosmicjs/sdk/?lang=original 项目主页：https://github.com/cosmicjs/cosmic-sdk-js#readme 源码仓库：https://github.com/cosmicjs/cosmic-sdk-js ## 关键信息（来自 npm 元数据） - 包体积（解压后）：62 kB，6 个文件 - 模块格式：ESM + CJS - TypeScript 类型：包内自带 - Node.js 要求：\>=18 - 运行依赖：0 个 - 首次发布：2023-03-23T16:12:23.300Z - 最新版本发布：2026-09-09T18:10:38.094Z - 近 30 天下载量：10040（2026-10-11 至 2026-11-09，npm 官方下载统计） - 已发布版本数：53（近 12 个月 9 个） ## 中文简介 官方JavaScript SDK用于宇宙. 获取内容,管理媒体,并在Next.js,节点和浏览器中生成AI. ## 安装 ```sh npm install @cosmicjs/sdk ``` 也可以使用：`pnpm add @cosmicjs/sdk`、`yarn add @cosmicjs/sdk`、`bun add @cosmicjs/sdk` ## README [![Cosmic](https://cdn.cosmicjs.com/a28c6df0-c98c-11ed-b01d-23d7b265c299-cosmicwordmarkonlight.svg)](https://www.cosmicjs.com/) # 宇宙 Java 脚本 SDK 官方客户端 [宇宙学](https://www.cosmicjs.com/)。获取内容,管理媒体,并在Next.js,Node和浏览器中生成AI. [![npm version](https://img.shields.io/npm/v/@cosmicjs/sdk.svg)](https://www.npmjs.com/package/@cosmicjs/sdk) [![npm downloads](https://img.shields.io/npm/dw/@cosmicjs/sdk.svg)](https://www.npmjs.com/package/@cosmicjs/sdk) [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-3178c6.svg)](https://www.typescriptlang.org/) [![Node.js >= 18](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org/) [![Package Checks](https://github.com/cosmicjs/cosmic-sdk-js/actions/workflows/main.yml/badge.svg)](https://github.com/cosmicjs/cosmic-sdk-js/actions/workflows/main.yml) [![MIT License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/cosmicjs/cosmic-sdk-js/blob/HEAD/LICENSE) [免费开始](https://app.cosmicjs.com/signup) • 妇女 [快速启动](https://www.cosmicjs.com/docs/quickstart) • 妇女 [实例](https://www.cosmicjs.com/docs/examples) • 妇女 [Next.js 向导](https://www.cosmicjs.com/headless-cms-for-nextjs) [宇宙学](https://www.cosmicjs.com/) 是一个 [无头CMS](https://www.cosmicjs.com/headless-cms) 配备用于创建内容的仪表板和用于向任何网站或应用程序发送内容的API。 这个软件包是正式的TypeScript客户端:输入结果,零运行时间依赖,在Next.js,Node.js 18+和浏览器中工作. ## 快开始 安装 SDK, 添加您的 Bucket 密钥 _弹匣 > 设置 > API 访问_,并在 Next.js App 路由器页面中获取内容. ```bash npm install @cosmicjs/sdk ``` ```env COSMIC_BUCKET_SLUG=your-bucket-slug COSMIC_READ_KEY=your-read-key ``` ```tsx import { createBucketClient } from '@cosmicjs/sdk'; const cosmic = createBucketClient({ bucketSlug: process.env.COSMIC_BUCKET_SLUG as string, readKey: process.env.COSMIC_READ_KEY as string, }); export default async function HomePage() { const { objects: posts } = await cosmic.objects .find({ type: 'posts' }) .props(['id', 'slug', 'title', 'metadata']) .limit(10); return (

Latest posts

); } ``` 需要特定形状时通过类型参数 : `find({ type: 'posts' })`。 。 。 . [浏览启动程序 →](https://www.cosmicjs.com/docs/examples) ## 安装 ```bash npm install @cosmicjs/sdk # or yarn add @cosmicjs/sdk # or bun add @cosmicjs/sdk ``` ```js import { createBucketClient } from '@cosmicjs/sdk'; ``` ## 目录 - [认证](https://npmcn.com/package/%40cosmicjs/sdk/#readme-authentication) - [获取对象](https://npmcn.com/package/%40cosmicjs/sdk/#readme-get-objects) - [创建、更新和删除对象](https://npmcn.com/package/%40cosmicjs/sdk/#readme-create-update-and-delete-objects) - [媒体](https://npmcn.com/package/%40cosmicjs/sdk/#readme-media) - [对象类型](https://npmcn.com/package/%40cosmicjs/sdk/#readme-object-types) - [订正](https://npmcn.com/package/%40cosmicjs/sdk/#readme-revisions) - [丰富文本和块](https://npmcn.com/package/%40cosmicjs/sdk/#readme-rich-text-and-blocks) - [大赦国际](https://npmcn.com/package/%40cosmicjs/sdk/#readme-ai) - [学多点](https://npmcn.com/package/%40cosmicjs/sdk/#readme-learn-more) ## 认证 在那个 [宇宙管理员仪表板](https://app.cosmicjs.com/login) 转到 _弹匣 > 设置 > API 访问_ 并复制你的巴基特弹和钥匙. ```js const cosmic = createBucketClient({ bucketSlug: process.env.COSMIC_BUCKET_SLUG, readKey: process.env.COSMIC_READ_KEY, }); ``` 添加 `writeKey` 用于创建、更新、删除、媒体上传和AI。 从不披露客户端代码中的写键 . ```js const cosmic = createBucketClient({ bucketSlug: process.env.COSMIC_BUCKET_SLUG, readKey: process.env.COSMIC_READ_KEY, writeKey: process.env.COSMIC_WRITE_KEY, }); ``` 添加 `previewToken` 读取草稿 [现场预览](https://www.cosmicjs.com/docs/api/preview) 没有写键. ```js const cosmic = createBucketClient({ bucketSlug: process.env.COSMIC_BUCKET_SLUG, readKey: process.env.COSMIC_READ_KEY, previewToken: process.env.COSMIC_PREVIEW_TOKEN, }); ``` ## 获取对象 物体是宇宙中内容的基本构件. 传出一个用于键入结果的通称, 或使用 `CosmicObject` 为公有领域. ### 获取多个对象 \[[见文件](https://www.cosmicjs.com/docs/api/objects#get-objects)\[ . \] ```js const { objects: posts } = await cosmic.objects .find({ type: 'posts', }) .props(['title', 'slug', 'metadata']) .limit(10); ``` ### 获取单个对象 \[[见文件](https://www.cosmicjs.com/docs/api/objects#get-a-single-object-by-slug)\[ . \] ```js const { object: page } = await cosmic.objects .findOne({ type: 'pages', slug: 'home', }) .props(['title', 'slug', 'metadata']); ``` ### 输入结果 ```ts type Post = { title: string; slug: string; metadata: { excerpt: string }; }; const { objects } = await cosmic.objects .find({ type: 'posts' }) .props(['title', 'slug', 'metadata']); ``` ### 查询助手 把它锁上 `find` 财务报告和审定财务报表 `findOne`数字 : | 方法 | 目的 | | --- | --- | | `.props(['title', 'slug'])` | 只返回列出的字段 | | `.limit(10)` | 页面大小`find` 仅限) | | `.skip(20)` | 用于平面的偏移 | | `.sort('-created_at')` | 按领域排序。 前缀 `-` 降级 | | `.depth(1)` | 解析嵌入对象引用 | | `.status('published')` | `published`, (中文(简体) ), `draft`,或 `any` | | `.after(id)` | 光标标记 | | `.useCache()` | 启用宇宙 CDN 缓存 | ## 创建、更新和删除对象 需要一个 `writeKey`。 。 。 . ### 创建对象 \[[见文件](https://www.cosmicjs.com/docs/api/objects#create-an-object)\[ . \] ```js await cosmic.objects.insertOne({ title: 'Blog Post Title', type: 'posts', metadata: { content: 'Here is the blog post content.', seo_description: 'This is the blog post SEO description.', featured_post: true, tags: ['javascript', 'cms'], }, }); ``` ### 更新对象 \[[见文件](https://www.cosmicjs.com/docs/api/objects#update-an-object)\[ . \] ```js await cosmic.objects.updateOne('object-id', { metadata: { content: 'Updated blog post content.', featured_post: false, }, }); ``` ### 删除对象 \[[见文件](https://www.cosmicjs.com/docs/api/objects#delete-an-object)\[ . \] ```js await cosmic.objects.deleteOne('object-id'); ``` ### 批量操作 \[[见文件](https://www.cosmicjs.com/docs/api/objects#batch-operations)\[ . \] 在一个呼叫中创建、更新和删除最多25个对象。 每次操作独立成功或失败. ```js const result = await cosmic.objects.batch([ { method: 'add', object: { title: 'Post 1', type: 'posts', metadata: { content: '...' } } }, { method: 'edit', object_id: 'object-id', object: { title: 'Updated Title' } }, { method: 'delete', object_id: 'another-object-id' }, ]); ``` ## 媒体 在媒体库中上传、列出和删除文件。 \[[见文件](https://www.cosmicjs.com/docs/api/media)\[ . \] ```js const { media } = await cosmic.media .find({ folder: 'images' }) .props(['name', 'url', 'imgix_url']) .limit(20); const { media: file } = await cosmic.media.findOne({ name: 'hero.png' }); await cosmic.media.insertOne({ media: bufferOrFile, folder: 'images', }); await cosmic.media.updateOne('media-id', { alt_text: 'Hero image' }); await cosmic.media.deleteOne('media-id'); ``` 上传的图像包括 `imgix_url` 用于调整大小和优化. ## 对象类型 阅读和管理内容模式. \[1\][见文件](https://www.cosmicjs.com/docs/api/object-types)\[ . \] ```js const { object_types } = await cosmic.objectTypes.find(); const { object_type } = await cosmic.objectTypes.findOne('posts'); await cosmic.objectTypes.insertOne({ title: 'Authors', slug: 'authors' }); await cosmic.objectTypes.updateOne('authors', { title: 'Writers' }); await cosmic.objectTypes.deleteOne('authors'); ``` ## 订正 列出并恢复对象修改 。 与 `previewToken` 以预览草稿。 \[[见文件](https://www.cosmicjs.com/docs/api/revisions)\[ . \] ```js const { revisions } = await cosmic.objectRevisions.find('object-id'); const { revision } = await cosmic.objectRevisions.findOne({ objectId: 'object-id', revisionId: 'revision-id', }); ``` ## 丰富文本和块 获取富有 文本块定义 [`@cosmicjs/rich-text`](https://www.npmjs.com/package/@cosmicjs/rich-text)\[[见文件](https://www.cosmicjs.com/docs/api/rich-text)\[ . \] ```bash npm install @cosmicjs/rich-text ``` ```tsx import { createBucketClient } from '@cosmicjs/sdk'; import { RichText } from '@cosmicjs/rich-text'; const cosmic = createBucketClient({ bucketSlug: process.env.COSMIC_BUCKET_SLUG as string, readKey: process.env.COSMIC_READ_KEY as string, }); const [{ object: post }, { blocks }] = await Promise.all([ cosmic.objects.findOne({ type: 'posts', slug: 'hello-world' }), cosmic.blocks.find(), ]); export default function Post() { return ; } ``` ## 大赦国际 生成文字,图像,视频,和音频. 需要一个 `writeKey`\[[见文件](https://www.cosmicjs.com/docs/api/ai)\[ . \] ### 文本 ```js const { text, usage } = await cosmic.ai.generateText({ prompt: 'Write a product description for a coffee mug', max_tokens: 500, }); ``` 当它们到达时,会流出迹象. `stream: true` 返回 a `TextStreamingResponse`;不需要铸造. ```js const stream = await cosmic.ai.generateText({ prompt: 'Tell me about coffee mugs', stream: true, }); for await (const chunk of stream) { if (chunk.text) process.stdout.write(chunk.text); } ``` 或使用 `cosmic.ai.stream({ prompt })`。通过传递分析图像 `media_url` 以您的及时. ### 图像、视频和音频 ```js const image = await cosmic.ai.generateImage({ prompt: 'A serene mountain landscape at sunset', folder: 'ai-generated-images', }); const icon = await cosmic.ai.generateImage({ prompt: 'Minimal coffee cup icon, flat vector, no text', format: 'svg', aspect_ratio: '1:1', }); const video = await cosmic.ai.generateVideo({ prompt: 'Product rotates smoothly with soft studio lighting', duration: 8, resolution: '720p', }); const extended = await cosmic.ai.extendVideo({ media_id: video.media.id, prompt: 'The camera pulls back to reveal the full scene', }); const audio = await cosmic.ai.generateAudio({ prompt: 'Welcome to the Cosmic Developer Podcast.', voice: 'nova', }); ``` 已生成的文件以 CDN URL 保存到您的媒体库 。 见 [AI 视频生成指南](https://github.com/cosmicjs/cosmic-sdk-js/blob/HEAD/docs/AI_VIDEO_GENERATION.md) 模型、期限和扩展细节,以及 [`examples/`](https://github.com/cosmicjs/cosmic-sdk-js/tree/HEAD/examples) 用于可运行的脚本. ## 学多点 - [文档](https://www.cosmicjs.com/docs) - [快速启动](https://www.cosmicjs.com/docs/quickstart) - [下一个.js](https://www.cosmicjs.com/headless-cms-for-nextjs) - [实例](https://www.cosmicjs.com/docs/examples) - [国 际](https://www.cosmicjs.com/docs/cli) - [MCP 服务器](https://www.cosmicjs.com/docs/mcp-server) - [API 参考](https://www.cosmicjs.com/docs/api) ## 社区支助 - [解析器](https://discord.gg/MSCwQ7D6Mg) (问题,错误报告) - [GitHub 图像](https://github.com/cosmicjs/cosmic-sdk-js) (议题、贡献) - [页:1](https://x.com/cosmicjs) (产品更新) - [YouTube (英语)](https://www.youtube.com/cosmicjs) (视频辅导) ## 宇宙学支持 [联系我们](https://www.cosmicjs.com/contact) 服务问题和定制计划. ## 捐款 这个项目使用 [更改列表](https://www.npmjs.com/package/@changesets/cli) 管理释放。 遵循以下步骤添加一个更改列表: - 运行 `npm run changeset` 命令和选择带有变化描述的释放类型. - 当有更改的 PR 合并为 `main` 分支, Github 将创建新的 PR, 并进行正确的版本更改和更改日志编辑 . - 何时 `codeowner` 合并生成的PR,它将发布软件包并创建一个Github发行. ## 许可证 本项目在以下标题下公布: [麻省理工学院](https://github.com/cosmicjs/cosmic-sdk-js/blob/HEAD/LICENSE) 执照. ## 常见问题 ### @cosmicjs/sdk 是什么？ 官方JavaScript SDK用于宇宙\. 获取内容,管理媒体,并在Next\.js,节点和浏览器中生成AI\. ### 如何安装 @cosmicjs/sdk？ 在项目目录运行 npm install @cosmicjs/sdk，或使用 pnpm add / yarn add / bun add。 ### @cosmicjs/sdk 支持 TypeScript 吗？ 支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。 ### @cosmicjs/sdk 支持 ESM 还是 CommonJS？ 同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。 ### @cosmicjs/sdk 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=18。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @cosmicjs/sdk 可以商用吗？ @cosmicjs/sdk 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @cosmicjs/sdk 的下载量有多少？ 根据 npm 官方下载统计，@cosmicjs/sdk 在 2026/10/11 – 2026/11/09 这 30 天内被下载 10,040 次，日均约 335 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cosmicjs/sdk 还在维护吗？ 最新版本 2\.4\.0 发布于 2026/09/10（2 个月前）；至今共发布 53 个版本，其中过去 12 个月发布了 9 个；首次发布于 2023/03/24。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。