Framer CMS — Server API 技能

通过 framer-api npm 包以编程方式管理 Framer CMS 内容。可推送文章、上传图片、创建集合（collection），以及发布（publish）/部署（deploy）——全部可通过终端完成，无需打开 Framer 应用。

首次设置（入门流程）

若用户在当前项目中首次使用该技能，请运行 references/onboarding.md 中描述的入门流程。

快速检查：查看用户的 .env 文件或环境变量中是否存在 FRAMER_PROJECT_URL 和 FRAMER_API_KEY。若缺失，请执行入门流程。

工作原理

本技能基于 Framer Server API（即 framer-api npm 包），该包通过 WebSocket 使用 API 密钥连接至 Framer 项目，提供完整的 CMS 增删改查（CRUD）、图片上传、发布与部署能力。

重要提示：项目中必须已安装 framer-api 包。若未安装，请运行：

npm i framer-api

所有操作均通过 ES 模块脚本（.mjs 文件）实现，并采用如下连接模式：

import { connect } from "framer-api"

// 重要：API 密钥需以纯字符串形式传入（第二个参数），而非 {apiKey: "..."}
const framer = await connect(process.env.FRAMER_PROJECT_URL, process.env.FRAMER_API_KEY)
try {
  // ... 执行操作 ...
} finally {
  await framer.disconnect()
}

可用操作

CMS 集合（Collections）

CMS 条目（Items，如文章、记录）

⚠️ 关键提示：如何更新 CMS 条目字段

setAttributes 方法具有 非直观的 API 设计 —— 字段值 必须 包裹在 fieldData 键下：

// ✅ 正确 —— 字段值包裹在 fieldData 中
await item.setAttributes({
  fieldData: {
    [titleFieldId]: { type: "string", value: "New Title" }
  }
})

// ❌ 错误 —— 值将被静默忽略，且不抛出错误
await item.setAttributes({
  [titleFieldId]: { type: "string", value: "New Title" }
})

// ❌ 错误 —— 同样会被静默忽略
await item.setAttributes({
  [titleFieldId]: "New Title"
})

支持部分更新：仅修改指定字段，其余字段保持不变。

非字段属性（如 slug、draft）应直接设于对象顶层，而非置于 fieldData 内：

await item.setAttributes({ slug: "new-slug", draft: false })

字段数据格式

创建或更新条目时，字段数据需以 字段 ID（而非字段名）为键：

const fields = await collection.getFields()
const titleField = fields.find(f => f.name === "Title")

await collection.addItems([{
  slug: "my-article",
  fieldData: {
    [titleField.id]: { type: "string", value: "My Article Title" },
  }
}])

支持的字段类型及其值格式：

图片

从公开 URL 上传图片，然后在 CMS 条目中引用返回的 asset：

const asset = await framer.uploadImage("https://example.com/photo.jpg")
// asset = { id, url, thumbnailUrl }

await item.setAttributes({
  fieldData: {
    [thumbnailField.id]: { type: "image", value: asset.url }
  }
})

发布（Publishing）与部署（Deployment）

// 创建预览部署
const result = await framer.publish()
// result = { deployment: { id }, hostnames: [...] }

// 将预览部署提升为生产环境
await framer.deploy(result.deployment.id)

每次部署至生产环境前，务必向用户确认。 发布预览是安全操作；而部署将直接影响线上环境。

项目信息与变更

await framer.getProjectInfo()       // { id, name, apiVersion1Id }
await framer.getCurrentUser()       // { id, name, avatar }
await framer.getPublishInfo()       // 当前部署状态
await framer.getChangedPaths()      // { added, removed, modified }
await framer.getChangeContributors() // 贡献者 UUID 列表
await framer.getDeployments()       // 全部部署历史

其他操作

常见工作流

向 CMS 推送一篇新文章

完整流程（含字段解析、图片上传及错误处理）请参见 references/cms-operations.md。

批量更新文章

const items = await collection.getItems()
for (const item of items) {
  await item.setAttributes({
    fieldData: {
      [metaField.id]: { type: "string", value: generateMeta(item) }
    }
  })
}

CMS 更改后执行发布

const changes = await framer.getChangedPaths()
if (changes.added.length || changes.modified.length || changes.removed.length) {
  const result = await framer.publish()
  console.log("预览地址:", result.hostnames)
  // 部署前请先向用户确认：await framer.deploy(result.deployment.id)
}

重要注意事项

• API 密钥作用域：每个密钥仅绑定一个项目。若需管理多个 Framer 站点，请分别存储多个密钥。
• WebSocket 连接：connect() 调用会建立持久化 WebSocket 连接。操作完成后务必调用 disconnect()；或使用 using framer = await connect(...) 实现自动清理。
• 使用字段 ID，而非字段名：CMS 操作均依赖字段 ID。务必先调用 getFields() 并将字段名解析为对应 ID。
• 图片字段：需传入 uploadImage() 返回的完整 framerusercontent.com URL，而非 asset ID。
• 代理方法：多数方法（如 getCollections、publish 等）均为代理方法 —— 它们不会出现在 Object.keys(framer) 中，但可正常调用。
• 速率限制：官方未明确文档化速率限制，但仍建议避免高频请求。对批量操作（如处理 100+ 条目）应加入小幅延迟。
• formattedText 字段：支持标准 HTML 标签（h1–h6、p、ul、ol、li、a、strong、em、img、blockquote、pre、code、table 等）。
• 草稿条目：条目可设置 draft: true；草稿内容默认不参与发布。
• 博客文章集合（Blog Posts collection）：由 "thisPlugin" 管理的集合仅可通过 API 读取，不可修改；仅 "user" 管理的集合支持写入操作。