📦 Framer CRM API — Framer CMS管理

通过 framer-api npm 包，以编程方式管理 Framer CMS 内容。无需打开 Framer 应用，即可在终端推送文章、上传图片、创建集合、发布/部署。

首次设置（引导）

如果用户首次在项目中使用该技能，请运行 references/onboarding.md 中描述的引导流程。 快速检查： 在用户的 .env 文件或环境中查找 FRAMER_PROJECT_URL 与 FRAMER_API_KEY。若缺失，则进行引导。

工作原理

本技能使用 Framer Server API（framer-api npm 包），通过 API Key 以 WebSocket 方式连接 Framer 项目，提供完整的 CMS CRUD、图片上传、发布与部署功能。

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

npm i framer-api

所有操作均采用 ES module 脚本（.mjs 文件），连接模式如下：

import { connect } from "framer-api"
// 重要：API key 作为普通字符串传入（第 2 参数），而非 {apiKey: "..."}
const framer = await connect(process.env.FRAMER_PROJECT_URL, process.env.FRAMER_API_KEY)
try {
  // ... 操作 ...
} finally {
  await framer.disconnect()
}

可用操作

CMS 集合

CMS 条目（文章、记录）

⚠️ 关键：如何更新 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 上传图片，然后将返回的 asset 用于 CMS 条目：

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
    }
  }
})

发布与部署

// 创建预览部署
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("Preview:", result.hostnames)
  // 询问用户后再：
  // await framer.deploy(result.deployment.id)
}

重要提示

• API key 作用域： 每个 key 仅绑定一个项目。多个 Framer 站点需存储多个 key。
• 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 集合： 由 "thisPlugin" 管理的集合通过 API 只读。仅 "user" 管理的集合可修改。