webflow-cli:troubleshooter

Webflow CLI 故障排查

使用诊断命令和自动修复功能诊断并解决 Webflow CLI 问题。

重要提示

所有诊断操作都必须使用 Bash 工具：

• 通过 Bash 工具执行诊断命令
• 使用 Read 工具检查配置文件
• 验证 CLI 是否已安装：webflow --version
• 检查身份验证：webflow auth login（如有需要）
• 使用 CLI 诊断标志：--verbose、--debug-bundler、--help
• CLI 工作流中不要使用 Webflow MCP 工具
• 所有 CLI 命令都必须带有适当的描述（而非上下文参数）

包管理器检测：

• 检查锁文件：package-lock.json（npm）、pnpm-lock.yaml（pnpm）、yarn.lock（yarn）
• 如果未找到锁文件，请询问用户要使用哪个包管理器（npm/pnpm/yarn）
• 所有安装和构建命令都使用检测到的包管理器

说明

阶段 1：识别问题

1. 询问用户描述问题：哪个命令执行失败，或出现了什么错误
2. 确定错误类别：
   • CLI 未安装或版本不正确
   • 身份验证失败
   • 构建/打包失败
   • 无法识别命令
3. 获取错误消息：获取准确的错误输出

阶段 2：运行诊断

4. 检查 CLI 安装情况：运行 webflow --version
5. 检查身份验证：如有需要，运行 webflow auth login
6. 使用 --verbose 运行命令：为失败的命令添加 --verbose 标志，以获取详细输出
7. 使用 --debug-bundler（如遇打包问题）：添加 --debug-bundler 标志运行命令，以查看打包器配置
8. 检查 --help：运行 webflow <command> --help，确认命令语法

阶段 3：分析并修复

9. 确定根本原因：分析错误消息和诊断输出
10. 提供修复方案：根据 CLI 错误给出具体解决方案
11. 应用修复：执行修复命令
12. 验证：重新运行原始命令，确认问题已解决

示例

示例 1：CLI 未安装

用户提示词：

Getting "webflow: command not found"

诊断：

🔍 Checking CLI Installation

Executing: webflow --version

Error: bash: webflow: command not found

❌ Webflow CLI not installed

修复：

📋 Fix: Install Webflow CLI

Executing: npm install -g @webflow/cli

✓ CLI installed

Verifying...
Executing: webflow --version

Output: @webflow/cli/1.5.2

✅ Issue resolved

示例 2：构建失败

用户提示词：

Build is failing but I don't know why

诊断：

🔍 Running Build with Diagnostics

Executing: webflow library bundle --verbose

Output:
[verbose] Loading webflow.json
[verbose] Found library config
[verbose] Building components from ./src/**/*.webflow.tsx
[verbose] Running bundler
Error: Failed to resolve import './missing-file.ts'

❌ Build failed: Missing import file

修复：

📋 Fix: Missing Import

Issue: Component imports './missing-file.ts' which doesn't exist

Solutions:
1. Create the missing file
2. Fix the import path
3. Remove the import if not needed

Check your component imports and ensure all files exist.

示例 3：打包配置问题

用户提示词：

Bundle is failing with webpack errors

诊断：

🔍 Checking Bundle Configuration

Executing: webflow library bundle --debug-bundler

Output:
[debug-bundler] Final bundler configuration:
{
  "entry": "./src/Component.tsx",
  "output": {
    "path": "/dist",
    "filename": "bundle.js"
  },
  "resolve": {
    "extensions": [".ts", ".tsx", ".js"]
  }
}

Error: Module not found: Can't resolve 'styled-components'

❌ Bundle failed: Missing dependency

修复：

📋 Fix: Install Missing Dependency

Executing: npm install styled-components

✓ Dependency installed

Retrying bundle...
Executing: webflow library bundle

✓ Bundle created successfully

✅ Issue resolved

指南

CLI 诊断命令

版本检查：

webflow --version
# or
webflow -V

命令帮助：

webflow --help                    # General help
webflow library --help            # Library commands help
webflow library bundle --help     # Specific command help

详细输出：

# Add --verbose to any command for detailed debugging
webflow library bundle --verbose
webflow cloud deploy --verbose
webflow extension bundle --verbose

打包器调试：

# Show final bundler configuration
webflow library bundle --debug-bundler
webflow extension bundle --debug-bundler

常见问题与修复方法

问题：找不到 CLI

• 诊断：webflow --version 执行失败
• 修复：npm install -g @webflow/cli
• 验证：webflow --version 显示版本号

问题：CLI 版本不正确

• 诊断：webflow --version 显示旧版本
• 修复：npm update -g @webflow/cli
• **验证：**已安装最新版本

问题：无法识别命令

• **诊断：**出现“Unknown command”错误
• **修复：**使用 webflow --help 检查命令
• **验证：**使用正确的命令语法

问题：身份验证失败

• **诊断：**出现“Not authenticated”错误
• 修复：webflow auth login
• **验证：**身份验证成功

问题：构建失败

• **诊断：**使用 --verbose 标志运行
• **修复：**修复详细输出中显示的错误
• **验证：**构建成功

问题：打包配置错误

• **诊断：**使用 --debug-bundler 标志运行
• **修复：**调整 webflow.json 中的打包器配置
• **验证：**打包成功

问题：缺少依赖项

• **诊断：**出现“Module not found”错误
• **修复：**运行 npm install 或安装指定的包
• **验证：**构建/打包成功

问题：node_modules 已损坏

• **诊断：**出现无法解释的构建失败
• 修复：rm -rf node_modules && npm install
• **验证：**构建成功

错误处理

CLI 未安装：

❌ Webflow CLI Not Found

Install:
npm install -g @webflow/cli

Verify:
webflow --version

Docs: https://developers.webflow.com/cli

需要身份验证：

❌ Authentication Failed

Fix:
webflow auth login

Follow browser prompts to authenticate

构建/打包失败：

❌ Build Failed

Run with diagnostics:
webflow library bundle --verbose --debug-bundler

This shows:
- Detailed build steps
- Import resolution
- Bundler configuration
- Exact error location

Fix the errors shown in output

未知错误：

❌ Unknown Issue

Gather info:
1. What command are you running?
2. Run command with --verbose flag
3. Check command syntax with --help
4. Share full error output

This helps identify the specific problem

文件操作

读取配置文件：

# View webflow.json
Read: webflow.json

# View package.json
Read: package.json

# View build output
Read: dist/

查找文件：

# Find config files
Glob: **/webflow.json

# Find components
Glob: src/**/*.webflow.tsx

# Find logs
Glob: **/*.log

最佳实践

始终从以下步骤开始：

1. 检查 CLI 版本：webflow --version
2. 检查命令语法：webflow <command> --help
3. 运行时启用详细输出：添加 --verbose 标志

对于构建／打包问题：

1. 使用 --verbose 查看详细输出
2. 使用 --debug-bundler 查看配置
3. 检查导入路径
4. 确认依赖项已安装

对于身份验证问题：

1. 运行 webflow auth login
2. 按照浏览器中的提示操作
3. 确认有权访问工作区

对于安装问题：

1. 检查 Node.js 版本：node --version
2. 全局安装 CLI：npm install -g @webflow/cli
3. 验证安装：webflow --version

快速参考

**工作流：**识别 → 诊断 → 修复 → 验证

诊断标志：

• --version / -V - 检查 CLI 版本
• --help / -h - 显示命令帮助
• --verbose - 输出详细的调试信息
• --debug-bundler - 显示打包器配置

常见修复方法：

• 未安装 → npm install -g @webflow/cli
• 版本错误 → npm update -g @webflow/cli
• 身份验证失败 → webflow auth login
• 构建失败 → 检查 --verbose 输出
• 打包错误 → 检查 --debug-bundler 输出
• 缺少依赖项 → npm install

文档： https://developers.webflow.com/cli