mcpField
W
webflow-code-component:troubleshoot-deploy

webflow-code-component:troubleshoot-deploy

github.com/webflow开发133986 次安装今天更新
代码仓库

关于 webflow-code-component:troubleshoot-deploy

用于排查 Webflow 代码组件部署问题的技能，面向部署失败或组件发布后异常的开发者。它按身份验证、构建、包大小、网络和配置等类别分析错误，并提供修复与验证步骤。

主要功能

  1. 01收集部署错误和日志
  2. 02按类别诊断故障原因
  3. 03提供具体修复步骤
  4. 04列出常见错误及对应处理
  5. 05指导部署结果验证
  6. 06整理升级排查所需信息

适用场景

  1. 01处理 library share 部署失败
  2. 02排查已发布组件无法渲染
  3. 03解决构建、配置或包大小错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/webflow/webflow-skills --skill webflow-code-component:troubleshoot-deploy

安装后在 Claude Code 中输入/webflow-code-component:troubleshoot-deploy确认已加载。

附带文件references/ERROR_CATALOG.md

详细介绍

部署故障排查

调试并修复 Webflow Code Components 的部署问题。

何时使用此技能

适用于：

  • webflow library share 报错失败
  • 组件已部署，但无法正常工作
  • 用户提供了部署错误消息
  • 出现了打包或编译错误

不适用于：

  • 尚未尝试部署（改用 deploy-guide）
  • 部署前验证（改用 pre-deploy-check）
  • 一般代码质量问题（改用 component-audit）

说明

阶段 1：收集信息

  1. 获取错误详情：

    • 询问完整的错误消息
    • 请用户提供 npx webflow library share 的输出
    • 检查 npx webflow library log 是否提供了更多信息

  2. 了解背景：

    • 是首次部署还是更新？
    • 最近做了哪些更改？
    • 之前能正常工作吗？
阶段 2：诊断

  1. 确定错误类别：

    • 身份验证错误
    • 构建/编译错误
    • 打包体积错误
    • 网络/上传错误
    • 配置错误

  2. 分析根本原因：

    • 解析错误消息
    • 检查常见原因
    • 确定具体问题
阶段 3：提供解决方案

  1. 给出具体修复方法：

    • 分步说明解决方法
    • 按需提供代码示例
    • 提供验证步骤

  2. 防止问题再次发生：

    • 解释问题发生的原因
    • 提出预防措施

常见错误参考

有关各类错误的详细解决方案，请参阅 references/ERROR_CATALOG.md。

快速参考
错误类别快速修复
"Authentication failed"身份验证在 Workspace Settings 中重新生成 API token
"Insufficient permissions"身份验证检查工作区角色和 token
"Module not found"构建npm install --save-dev @webflow/react
"TypeScript errors"构建运行 npx tsc --noEmit 查找错误
"Unexpected token"构建检查文件扩展名是否为 .tsx
"Bundle size exceeds limit"打包对导入内容进行 Tree-shaking，并延迟加载大型组件
"Component not rendering"运行时检查 SSR 问题和浏览器控制台
"Styles not appearing"运行时在 .webflow.tsx 文件中导入 CSS
"webflow.json not found"配置在项目根目录创建 webflow.json
"No components found"配置检查 glob 模式和文件扩展名
"Invalid JSON in webflow.json"配置修正 JSON 语法（尾随逗号、注释）
"429 Too Many Requests"网络等待 60 秒后重试
"Request timed out"网络检查网络连接、代理和 Webflow 状态
"JavaScript heap out of memory"内存NODE_OPTIONS="--max-old-space-size=4096"
"Circular dependency"构建提取共享代码，打破导入循环
最常见的修复方法

身份验证：

# Regenerate token, then:
export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token
npx webflow library share

缺少依赖项：

npm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react

SSR 问题：

// Wrap browser APIs in useEffect or disable SSR:
declareComponent(Component, { options: { ssr: false } });

缺少样式：

// In .webflow.tsx, import styles:
import "./Component.module.css";

调试命令

# Check recent deploy logs
npx webflow library log

# Verbose deploy output (shows detailed errors)
npx webflow library share --verbose

# Type check without deploying
npx tsc --noEmit

验证

满足以下所有条件，即表示问题已解决：

成功标准验证方法
部署完成且没有错误npx webflow library share 正常退出
组件显示在 Designer 中在 Designer 中打开 Add 面板，并找到你的库
导入日志确认成功npx webflow library log 显示导入成功

指南

错误分析流程
  1. 阅读完整的错误消息 - 通常其中包含解决方法
  2. 检查错误类别 - 身份验证、构建、打包或运行时
  3. 查找文件路径 - 定位到具体位置
  4. 检查行号 - 用于代码错误
  5. 搜索错误消息 - 可能是已知问题
何时升级处理

如果所有解决方案都不起作用，请在升级处理前收集以下数据：

  1. 部署日志：npx webflow library log
  2. 详细输出：npx webflow library share --verbose
  3. Node.js 版本：node -v
  4. 软件包版本：npm list @webflow/webflow-cli @webflow/data-types @webflow/react
  5. 配置：webflow.json 的内容
  6. 错误消息：完整的错误输出（不只是摘要行）

然后：

  • 查看 Webflow 状态页面，确认是否发生故障
  • 在 Webflow 社区论坛中搜索你的错误消息
  • 联系 Webflow 支持，并提供上述收集的数据

评论

支持 Markdown