webflow-code-component:deploy-guide

部署指南

引导用户将代码组件库部署到 Webflow。

何时使用此技能

适用情况：

• 用户已准备好将组件部署到 Webflow
• 用户询问如何共享、发布或部署组件库
• 首次向工作区部署
• 需要逐步讲解部署流程

不适用情况：

• 部署失败（改用 troubleshoot-deploy）
• 只需在部署前进行验证（改用 pre-deploy-check）
• 设置本地开发环境（改用 local-dev-setup）

**注意：**CLI 命令为 webflow library share。此技能面向用户时使用“部署”一词。

说明

阶段 1：部署前检查

1. 确认项目已准备就绪：

   • 检查 webflow.json 配置
   • 确保已安装所有依赖项
   • 执行 pre-deploy-check 技能检查

2. 检查身份验证状态：

   • 查找是否有包含 API 令牌的现有 .env 文件
   • 如果已设置，则验证 WEBFLOW_WORKSPACE_API_TOKEN
   • 如有需要，准备进行身份验证

3. 确认部署目标：

   • 要部署到哪个工作区？
   • 创建新库还是更新现有库？

阶段 2：身份验证

4. 引导用户完成身份验证：
   • 交互式：按照 CLI 提示操作
   • CI/CD：使用 --api-token 标志
   • 如有需要，说明如何获取工作区 API 令牌

阶段 3：部署

5. 执行部署：
   • 运行 npx webflow library share
   • 留意错误
   • 捕获输出

阶段 4：验证

6. 验证部署：

   • 在 Webflow Designer 中检查组件
   • 测试组件功能
   • 确认所有组件均已显示

7. 提供后续步骤：

   • 说明如何在 Designer 中使用组件
   • 说明如何在以后更新组件
   • 介绍常见的部署后任务
   • 如果部署失败，请使用 troubleshoot-deploy 诊断并修复问题

部署工作流

标准部署

📦 Deploying Code Components

Step 1: Pre-flight checks
├── webflow.json ✅
├── Dependencies ✅
└── Build test ✅

Step 2: Authentication
├── Checking for existing auth...
└── Found valid token ✅

Step 3: Deploying
├── Bundling components...
├── Uploading to workspace...
└── Processing...

Step 4: Verification
├── Library registered ✅
└── 4 components available ✅

🎉 Deployment Complete!

CI/CD 部署

# Set environment variable
export WEBFLOW_WORKSPACE_API_TOKEN=your-token-here

# Deploy without prompts
npx webflow library share --no-input

示例

用户提示词：

Deploy my components to Webflow

回复：

🚀 Deploy Guide: Code Components

Let me guide you through deploying your component library.

---

## Step 1: Pre-Flight Checks

Running validation...

✅ webflow.json configured
✅ Dependencies installed
✅ Build succeeds
✅ Bundle size: 2.3MB (under 50MB limit)

All checks passed! Ready to deploy.

---

## Step 2: Authentication

**Option A: Interactive (Recommended for first time)**

Run the deploy command:
```bash
npx webflow library share

此操作将：

1. 打开浏览器以登录 Webflow
2. 提示你授权此应用
3. 将凭据保存到 .env

选项 B：API 令牌（适用于 CI/CD 或回访用户）

1. 获取工作区 API 令牌：

   • 前往 Webflow Dashboard
   • 转到工作区设置
   • 找到“Apps & Integrations” → “Manage”
   • 在“Workspace API Access”下，点击“Generate API Token”
   • 复制令牌

2. 使用令牌运行：

npx webflow library share --api-token YOUR_TOKEN_HERE

或者设置环境变量：

export WEBFLOW_WORKSPACE_API_TOKEN=YOUR_TOKEN_HERE
npx webflow library share

---

第 3 步：部署

准备好部署了吗？运行：

npx webflow library share

预期输出：

✓ Bundling components...
✓ Authenticating...
✓ Uploading library...
✓ Processing...

Library "My Component Library" successfully shared!

Components:
- Button
- Card
- Accordion
- Modal

View in Designer: Open any site in your workspace

---

第 4 步：在 Designer 中验证

部署后：

1. 打开工作区中任意站点的 Webflow Designer
2. 打开添加面板（按 A 键或点击 + 按钮）
3. 找到“Components”部分
4. 在自定义组件下找到你的库
5. 将组件拖到画布上进行测试

---

第 5 步：后续步骤

✅ 你的组件已上线！

以后更新组件：

# Make your changes, then re-deploy
npx webflow library share

重要说明：

• 更新会替换整个库（不支持部分更新）
• 现有组件实例会自动更新
• 不要重命名 .webflow.tsx 文件（会导致实例失效）

---

💡 提示：

• 将 .env 添加到 .gitignore，以保护你的令牌
• 使用 --verbose 标志调试问题
• 运行 npx webflow library log 查看近期部署日志

---

**Example: First-Time Setup**

🚀 部署指南：首次设置

我看到这是你第一次部署。下面我将带你完整完成设置。

---

第 1 步：获取工作区 API 令牌

你需要工作区 API 令牌才能进行部署：

1. 打开 Webflow Dashboard 前往 webflow.com 并登录

2. 转到工作区设置 点击工作区名称 → Settings

3. 找到 API 访问权限 前往“Apps & Integrations” → “Manage”

4. 生成令牌 在“Workspace API Access”下：

   • 点击“Generate API Token”
   • 复制令牌（之后将无法再次查看！）

5. 保存令牌 将其添加到 .env 文件：

   WEBFLOW_WORKSPACE_API_TOKEN=your-token-here
   

   ⚠️ 将 .env 添加到 .gitignore：

   echo ".env" >> .gitignore
   

---

步骤 2：部署

现在运行：

npx webflow library share

CLI 将：

1. 从 .env 读取你的令牌
2. 打包你的组件
3. 上传到你的工作区

---

步骤 3：验证

成功部署后：

1. 打开 Webflow Designer
2. 按下“A”打开添加面板
3. 在组件部分找到你的组件
4. 将组件拖到画布上进行测试

---

🎉 首次部署完成！

后续部署会更简单：

# Just run this after making changes
npx webflow library share

---

**Example: CI/CD Setup**

🚀 部署指南：CI/CD 设置

为你的流水线设置自动部署。

---

GitHub Actions 示例

创建 .github/workflows/deploy.yml：

name: Deploy to Webflow

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Node.js
        uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: Install dependencies
        run: npm ci

      - name: Deploy to Webflow
        env:
          WEBFLOW_WORKSPACE_API_TOKEN: ${{ secrets.WEBFLOW_WORKSPACE_API_TOKEN }}
        run: npx webflow library share --no-input

---

在 GitHub 中添加密钥

1. 前往你的仓库 → Settings → Secrets and variables → Actions
2. 点击“New repository secret”
3. 名称：WEBFLOW_WORKSPACE_API_TOKEN
4. 值：你的工作区 API 令牌
5. 点击“Add secret”

---

CI/CD 的关键标志

npx webflow library share --no-input

• --no-input：禁用交互式提示
• 自动使用 WEBFLOW_WORKSPACE_API_TOKEN 环境变量

---

可选：添加 TypeScript 检查

- name: Type check
  run: npx tsc --noEmit

---

✅ CI/CD 已配置！

现在，每次推送到 main 时，都会自动部署你的组件。

## Validation

After deployment, verify success with these checks:

| Check | How to Verify |
|-------|---------------|
| Deploy completed | `npx webflow library share` exited without errors |
| Components visible | Open Designer Add panel → find your library |
| Import logs clean | `npx webflow library log` shows successful import |
| Bundle size OK | Output shows bundle under 50MB |
| Props work | Drag component onto canvas, verify props in right panel |

## Guidelines

### Terminology

The CLI command is `webflow library share`. This skill uses "deploy" as the user-facing term for consistency with common developer vocabulary. See the [CLI reference](../../references/CODE_COMPONENTS_REFERENCE.md) (Section 12) for full command documentation.

### Authentication Methods

| Method | Use Case | Command |
|--------|----------|---------|
| Interactive | First time, local dev | `npx webflow library share` |
| Environment variable | CI/CD, automation | Set `WEBFLOW_WORKSPACE_API_TOKEN` |
| CLI flag | One-off with different token | `--api-token TOKEN` |

### Pre-Deploy Checklist

Before every deployment:

- [ ] `npm install` is up to date
- [ ] Build succeeds locally
- [ ] Bundle under 50MB
- [ ] All component tests pass
- [ ] No SSR-breaking code (or ssr: false set)
- [ ] Props have default values where supported (not available for Link, Image, Slot, ID)

### Common Deploy Issues

| Issue | Cause | Solution |
|-------|-------|----------|
| "Authentication failed" | Invalid/expired token | Regenerate workspace token |
| "Bundle too large" | Over 50MB | Optimize dependencies |
| "Library not found" | Wrong workspace | Check token workspace |
| "Build failed" | Code errors | Fix compilation errors |

### CLI Flags Reference

All flags for `npx webflow library share`:

| Flag | Description | Default |
|------|-------------|---------|
| `--manifest` | Path to `webflow.json` file | Scans current directory |
| `--api-token` | Workspace API token | Uses `WEBFLOW_WORKSPACE_API_TOKEN` from `.env` |
| `--no-input` | Skip interactive prompts (for CI/CD) | No |
| `--verbose` | Display more debugging information | No |
| `--dev` | Bundle in development mode (no minification) | No |

### Rollback & Versioning

- Each `library share` replaces the **entire** library — there are no partial updates
- There is **no built-in rollback** — use git to revert changes and re-deploy
- **Never rename `.webflow.tsx` files** — renaming creates a new component and removes the old one, breaking all existing instances in projects

### Debugging Commands

```bash
# Check recent deploy logs
npx webflow library log

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

# Local bundle verification (catches build errors before deploying)
npx webflow library bundle --public-path http://localhost:4000/

CI/CD 部署

上面的 GitHub Actions 示例适用于任何 CI 系统。关键要素如下：

# Generic CI pattern:
npm ci                                        # Install dependencies
npx webflow library share --no-input          # Deploy without prompts
# Requires WEBFLOW_WORKSPACE_API_TOKEN env var

部署后验证

部署后务必进行验证：

1. 检查 Designer：组件显示在添加面板中
2. 测试拖放：组件会在画布上呈现
3. 测试属性：可在右侧面板中编辑属性
4. 测试预览：组件在预览模式下正常工作
5. 测试发布：组件在已发布的网站上正常工作