SuperAPI AI 工具集

framer-common-errors

编程与开发

查看项目

更新于 10-16 07:07

技能介绍

用途

Framer Common Errors 是一个针对 Framer 插件、组件与 Server API 常见错误与异常的诊断参考技能,用于在遇到 Framer 报错、调试失败请求或排查集成问题时,快速定位原因并应用修复。

主要能力

该技能提供以下常见错误的成因与修复说明:

  • 插件未在编辑器中显示:原因是开发服务器未运行或插件未注册。修复方式为运行 npm run dev 启动 Vite 开发服务器,然后在 Framer 中通过 Plugins > Development 选择插件。
  • framer is not defined:原因是在 Framer 编辑器 iframe 上下文之外调用 framer API。修复方式:来自 framer-plugin 的 framer 全局变量仅在编辑器内有效;服务端访问应改用 framer-api 包。示例:插件(编辑器)使用 import { framer } from 'framer-plugin';,服务端(无头)使用 import { framer } from 'framer-api';。
  • 组件在画布上渲染为空白:原因是组件代码中的运行时错误被 Framer 吞掉。修复方式为打开 Framer 浏览器控制台(右键 > 检查)查看错误。常见原因包括:组件缺少 export default、未定义且无默认值的 props、被 CORS 阻止的 fetch 请求错误。
  • addPropertyControls 不显示:原因是在错误的组件上调用或导入错误。修复方式:必须从 'framer' 而非 'framer-plugin' 导入,且必须在组件定义之后调用。
  • 代码覆盖(Code Override)不生效:原因是覆盖函数未返回正确结构。修复方式:覆盖必须返回 Override 类型对象(Framer Motion props)。正确示例返回 { whileHover: { scale: 1.1 } };错误情况为缺少返回类型或返回 JSX。
  • Server API WebSocket 连接失败:原因是 API 密钥无效、站点 ID 错误或网络阻止 WSS。修复方式包括:验证 API 密钥是否有效(应以 framer_sk_ 开头)、验证站点 ID、测试 WebSocket 连通性(curl -s https://api.framer.com/health)。
  • CMS 集合字段类型无效:原因是使用了不支持的字段类型字符串。有效类型为:string、formattedText、number、boolean、date、link、image、color、enum、slug。
  • 代码组件中的 CORS 错误:原因是组件中的 Fetch API 被浏览器 CORS 策略阻止。修复方式为使用 CORS 代理或确保 API 返回正确的 Access-Control-Allow-Origin 头。Framer 组件在浏览器中运行,适用相同的 CORS 规则。

使用方式

使用前需具备:授权站点所有者、不透明事件 ID、脱敏诊断信息以及安全的暂存复现路径。

处理流程:将问题归类为发布、域名、资源、访问、集成或可用性;在暂存页面复现;应用最小可逆修正;验证恢复与安全失败响应。

输出回执包含:类别、不透明关联 ID、操作、验证、负责人与后续跟进。需确保访客数据、令牌与页面内容不出现在支持证据中。

错误处理:在访问、域名或意外目标失败时,暂停发布或集成变更。使用回滚,并将重复失败上报给站点所有者。

示例:破坏一个虚构的暂存发布配置,恢复它,并验证生产站点未受影响,同时回执中不包含访客或凭据数据。

快速诊断命令:

# 检查 Framer API 是否可达
curl -s https://api.framer.com/health

# 验证 npm 包
npm list framer-plugin framer-api framer

# 检查代码中的常见问题
grep -r "from 'framer'" src/ --include="*.tsx" | head -10

适用场景

适用于 Framer 插件开发、组件调试、Server API 集成排错,以及 CMS 集合配置与代码组件网络请求问题的定位。

限制

资料未提供该技能的具体收费、价格、平台支持范围或效果保证。部分错误修复依赖具体项目环境,需结合实际代码与配置验证。