webflow-code-component:pre-deploy-check

构建验证

在部署前验证代码组件，以便尽早发现问题。

何时使用此技能

适用场景：

• 用户即将部署，并希望先检查问题
• 在运行 webflow library share 前主动验证
• 用户要求验证、检查或确认其组件
• 对组件进行重大更改后

不适用场景：

• 部署已经失败（请改用 troubleshoot-deploy）
• 仅用于本地开发
• 审计代码质量（请改用 component-audit）

说明

阶段 1：项目结构检查

1. 确认 webflow.json 存在：

   • 检查必需字段（library.name、library.components）
   • 验证 glob 模式是否匹配组件文件 — 推荐模式为 "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"，涵盖所有受支持的扩展名
   • 如果指定了 globals 路径，检查该文件是否存在且可导入
   • 如果指定了 bundleConfig 路径，检查该文件是否存在

2. 检查依赖项：

   • 确认已安装 @webflow/webflow-cli
   • 确认已安装 @webflow/data-types
   • 确认已安装 @webflow/react
   • 检查版本兼容性（检查已安装的版本，不要假定特定版本）

3. 确认组件文件：

   • 查找所有符合 glob 模式的 .webflow.tsx / .webflow.ts 文件
   • 确保存在相应的 React 组件
   • 检查是否有孤立的定义文件

4. 验证 .webflow.tsx 文件中的导入：

   • 必须从 @webflow/react 导入 declareComponent
   • （如果定义了 props）必须从 @webflow/data-types 导入 props
   • 必须导入要声明的实际 React 组件

阶段 2：组件分析

5. 逐个检查组件：

   • 是否使用组件和配置对象调用了 declareComponent
   • 配置中是否提供了 name
   • 所有 props 是否都有 name 属性，并在适用时设置了适当的 defaultValue
   • 属性类型是否有效——支持以下 11 种类型：
     • Text（别名：String）——单行文本输入
     • RichText——带格式的多行文本
     • TextNode——可在画布上编辑的单行/多行文本
     • Link——URL 输入（返回 { href, target, preload } 对象）
     • Image——图片上传与选择
     • Number——数字输入
     • Boolean——真/假切换
     • Variant——包含预定义选项的下拉菜单（需要 options 数组）
     • Visibility——显示/隐藏控件
     • Slot——用于放置子组件的内容区域
     • ID——HTML 元素 ID

6. 验证组件选项：

   • 如果存在 options 对象，请验证：
     • applyTagSelectors 是布尔值（默认值：false）——在 Shadow DOM 中启用站点标签选择器
     • ssr 是布尔值（默认值：true）——控制服务端渲染

7. 检查 SSR 问题：

   • 扫描 useEffect 或受保护代码块之外的仅限浏览器 API 用法：
     • window、document、localStorage、sessionStorage、navigator
   • 标记动态/个性化内容模式（用户专属仪表板、已验证身份的视图）
   • 标记无法从 SSR 中获益的繁重/交互式 UI（图表、3D 场景、地图、动画密集型元素）
   • 标记非确定性输出（服务器端与客户端的随机数、基于时间且结果不同的值）
   • 如果组件完全是交互式的或依赖浏览器，建议在选项中设置 ssr: false

8. 检查样式：

   • 确认样式已在 .webflow.tsx 中导入，或通过 globals 文件导入
   • 检查是否使用了站点类——站点类在 Shadow DOM 中不起作用
   • 站点变量可用：var(--variable-name, fallback)
   • 继承的 CSS 属性可用：font-family: inherit
   • 只有在组件选项中设置了 applyTagSelectors: true，标签选择器才可用
   • 如果使用了 CSS-in-JS，请验证其设置（参见下文的 CSS-in-JS 检测）

9. 检查 Shadow DOM 与 React Context 的问题：

   • 如果组件使用插槽（props.Slot），并且导入/使用了 useContext 或 Context Provider：
     • 警告：插槽中的父组件和子组件无法共享 React Context——每个子组件都在独立的 Shadow DOM 中使用单独的 React 根节点渲染
     • 建议替代方案：Nano Stores、自定义事件、URL 参数或浏览器存储

阶段 3：构建测试

10. 运行 TypeScript/构建检查：

    • 检查 TypeScript 编译错误
    • 验证所有导入是否正确解析
    • 识别任何构建时问题

11. 检查打包体积：

    • 如果存在构建输出，请确认打包总体积低于 50MB（最大打包限制）
    • 如果超出限制，请标记为错误并建议优化

12. 运行本地打包测试（可选，建议用户执行）：

    • 建议运行 npx webflow library bundle --public-path http://localhost:4000/，在分享前测试打包
    • 如果出现打包问题，建议使用 --debug-bundler 标志检查最终的 webpack 配置

阶段 4：检测框架特定的设置

13. CSS-in-JS 库检测：

    • 如果项目使用 styled-components：验证是否已安装 @webflow/styled-components-utils，以及 styledComponentsShadowDomDecorator 是否已从 globals decorators 数组中导出
    • 如果项目使用 Emotion 或 Material UI（@emotion/styled、@emotion/react、@mui/material）：验证是否已安装 @webflow/emotion-utils，以及 emotionShadowDomDecorator 是否已从 globals decorators 数组中导出

14. Tailwind CSS 检测：

    • 如果项目使用 Tailwind CSS（依赖项中包含 tailwindcss）：
      • 验证是否已安装 @tailwindcss/postcss
      • 验证 postcss.config.mjs 是否存在且包含 @tailwindcss/postcss 插件
      • 验证 globals 文件中是否导入了 Tailwind CSS（例如，在 globals.css 中使用 @import "tailwindcss"）

15. Sass/Less 预处理器检测：

    • 如果项目使用 Sass（存在 .scss 文件或依赖项中包含 sass）：验证是否已安装 sass 和 sass-loader，并且 webpack 配置添加了 .scss 规则
    • 如果项目使用 Less（存在 .less 文件或依赖项中包含 less）：验证是否已安装 less 和 less-loader，并且 webpack 配置添加了 .less 规则
    • 对于两者：验证 webflow.json 中是否设置了 bundleConfig，并指向 webpack 配置

16. Webpack 自定义配置验证（如果指定了 bundleConfig）：

    • 验证指定路径下的文件是否存在
    • 验证是否使用 CommonJS 导出（module.exports）
    • 如果尝试覆盖受限属性，则发出警告：entry、output、target（这些属性会被静默过滤）
    • 验证 module.rules 是否使用函数语法 (currentRules) => { ... }，而非数组

阶段 5：报告结果

17. 生成验证报告：
    • 列出所有已执行的检查
    • 显示通过/失败/警告状态
    • 为失败项提供修复建议
    • 指明是否已准备好部署

验证检查

必需检查

检查	严重性	说明
webflow.json 存在	错误	CLI 必需
已安装依赖项	错误	@webflow/webflow-cli、@webflow/data-types、@webflow/react
组件文件存在	错误	React + 定义文件必须存在
已调用 declareComponent	错误	必须在 .webflow.tsx 中使用正确的导入
属性类型有效	错误	仅支持这 11 种类型（Text/String、RichText、TextNode、Link、Image、Number、Boolean、Variant、Visibility、Slot、ID）
构建成功	错误	无编译错误
包大小 < 50MB	错误	Webflow 强制执行最大包大小限制

警告检查

检查	严重性	说明
属性具有默认值	警告	改善设计器体验
SSR 兼容性	警告	浏览器 API、动态内容、复杂 UI、非确定性输出
已导入样式	警告	样式可能不会显示在 Shadow DOM 中
Site class 的使用	警告	Site class 在 Shadow DOM 中不起作用——请使用组件专属 class
Shadow DOM + Context	警告	Slot 会阻止父级与子级之间共享 React Context
CSS-in-JS 装饰器	警告	styled-components/Emotion 需要 Shadow DOM 装饰器
Tailwind 设置	警告	缺少 postcss 配置或 globals 导入
Sass/Less 设置	警告	缺少加载器或 webpack 配置
Webpack 受限属性	警告	对 entry、output、target 的覆盖会被静默忽略
Webpack 规则格式	警告	必须使用函数语法，而非数组
组件选项	警告	applyTagSelectors 和 ssr 必须为布尔值
Glob 模式覆盖范围	警告	模式应涵盖所有支持的扩展名（.js、.jsx、.mjs、.ts、.tsx）
bundleConfig 文件	警告	如果在 webflow.json 中指定了文件，则该文件必须存在

信息检查

检查项	严重程度	描述
组件数量	信息	组件数量
Prop 数量	信息	每个组件的 Prop 数量
包大小	信息	当前包大小与 50MB 限制的对比
检测到的框架	信息	CSS-in-JS、Tailwind、Sass/Less 的使用情况

示例

用户提示词：

Check if my components are ready to deploy

响应：

🔍 Build Validation: My Component Library

Running pre-deployment checks...

---

## Project Structure

✅ webflow.json found
✅ library.name: "My Component Library"
✅ library.components: "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"
✅ globals: "./src/globals.ts"
✅ bundleConfig: not specified (using defaults)

---

## Dependencies

✅ @webflow/webflow-cli: installed
✅ @webflow/data-types: installed
✅ @webflow/react: installed
✅ react: installed
✅ typescript: installed

---

## Frameworks Detected

✅ Tailwind CSS detected
  ✅ @tailwindcss/postcss installed
  ✅ postcss.config.mjs found
  ✅ globals.css imports Tailwind

---

## Components Found (4)

### 1. Button ✅
- File: src/components/Button/Button.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Button component
- Props: label (Text), variant (Variant), disabled (Boolean)
- All props have defaults ✅
- SSR compatible ✅
- Options: applyTagSelectors: true ✅
- Styles imported ✅

### 2. Card ✅
- File: src/components/Card/Card.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Card component
- Props: title (Text), image (Image), content (RichText), link (Link)
- All props have defaults ✅
- SSR compatible ✅
- Styles imported ✅

### 3. Modal ⚠️
- File: src/components/Modal/Modal.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Modal component
- Props: title (Text), isOpen (Boolean), content (Slot)
- All props have defaults ✅
- ⚠️ SSR Issue: Uses `document.body` in render
  → Suggestion: Add `ssr: false` to options or wrap in useEffect
- Styles imported ✅

### 4. CartIcon ⚠️
- File: src/components/CartIcon/CartIcon.webflow.tsx
- Imports: ✅ declareComponent, ✅ CartIcon component
- Props: none
- ⚠️ Missing props - component has no editable properties
  → Suggestion: Consider adding props for designer customization
- ⚠️ Uses localStorage without SSR guard
  → Suggestion: Wrap in useEffect or useState initializer
- Styles imported ✅

---

## Build Test

✅ Build completed successfully
✅ No TypeScript errors
✅ No webpack errors
✅ Bundle size: 2.3MB / 50MB limit

---

## Summary

| Category | Status |
|----------|--------|
| Project Structure | ✅ Pass |
| Dependencies | ✅ Pass |
| Frameworks | ✅ Pass |
| Components | ⚠️ 2 warnings |
| Build | ✅ Pass |

---

## Ready to Deploy: ⚠️ WITH WARNINGS

You can deploy, but consider fixing these issues:

1. **Modal SSR Issue**
   Add to Modal.webflow.tsx:
   ```typescript
   options: {
     ssr: false
   }

2. CartIcon 的 localStorage 用法 更新 CartIcon.tsx：

   const [count, setCount] = useState(() => {
     if (typeof window === "undefined") return 0;
     return parseInt(localStorage.getItem("cartCount") || "0");
   });
   

---

💡 部署：npx webflow library share 💡 先在本地测试：npx webflow library bundle --public-path http://localhost:4000/

---

**Example: Build Failure**

🔍 构建验证：我的组件库

正在运行部署前检查……

---

项目结构

✅ 找到 webflow.json ⚠️ library.components 使用了范围过窄的 glob："./src//*.webflow.tsx" → 建议：使用 "./src//*.webflow.@(js|jsx|mjs|ts|tsx)"，以涵盖所有受支持的扩展名

---

依赖项

❌ 缺少：@webflow/react 修复方法：npm install --save-dev @webflow/react

---

构建测试

❌ 构建失败

src/components/Button/Button.webflow.tsx 中的错误：

Module not found: Error: Can't resolve '@webflow/react'

---

摘要

类别	状态
依赖项	❌ 1 个错误
构建	❌ 失败

---

准备部署：❌ 否

部署前请修复以下问题：

1. 安装缺失的依赖项

   npm install --save-dev @webflow/react
   

2. 重新运行验证 安装完成后，再次运行此检查。

---

**Example: CSS-in-JS Missing Decorator**

🔍 构建验证：我的组件库

---

检测到的框架

⚠️ 检测到 styled-components，但未配置 Shadow DOM 装饰器 → 安装：npm install @webflow/styled-components-utils → 添加到 globals.ts： typescript import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator]; → 在 webflow.json 中引用 globals： json { "library": { "globals": "./src/globals.ts" } }

否则，styled-components 样式将被注入 document.head， 而不是 Shadow DOM 中，导致组件无法显示样式。

---

**Example: Webpack Config Issues**

🔍 构建验证：我的组件库

---

Webpack 配置

⚠️ webpack.webflow.js：module.rules 使用了数组语法 → 必须使用函数语法：rules: (currentRules) => { return [...]; } → 数组语法无法使用——函数会接收当前规则以便扩展

⚠️ webpack.webflow.js：覆盖了 output 属性 → output 属性受限，将被静默忽略 → 受限属性：entry、output、target

💡 使用 --debug-bundler 标志检查最终合并后的 webpack 配置： npx webflow library bundle --debug-bundler

---

**Example: Shadow DOM Context Warning**

找到的组件（2）

1. ThemeProvider ⚠️

• 文件：src/components/ThemeProvider/ThemeProvider.webflow.tsx

• Props：theme (Variant)、children (Slot)

• ⚠️ Shadow DOM + React Context 问题： 组件使用了 Slot prop 和 React Context (ThemeContext)。 放置在插槽中的子项会在独立的 Shadow DOM 容器中渲染， 且各自拥有独立的 React 根节点——无法访问此 Context。

  跨组件状态的替代方案：

  • Nano Stores（轻量级响应式状态）
  • 自定义事件（window.dispatchEvent/addEventListener）
  • URL 参数（用于可共享状态）
  • 浏览器存储（localStorage/sessionStorage）

---

## Guidelines

### Validation Order

Run checks in this order for efficiency:

1. Project structure (fast, catches obvious issues)
2. Dependencies (medium, required for build)
3. Component analysis (medium, catches code issues)
4. Framework detection (medium, validates CSS-in-JS/Tailwind/Sass setup)
5. Build test (slow, but required)

### SSR Detection Patterns

Look for these patterns that indicate SSR issues:

```typescript
// Direct browser API usage (will break SSR)
window.innerWidth
document.getElementById
localStorage.getItem
navigator.userAgent
sessionStorage.getItem

// Dynamic/personalized content (may cause hydration mismatch)
// User-specific dashboards, authenticated views

// Heavy/interactive UI (SSR adds no value, re-renders anyway)
// Charts, 3D scenes, maps, animation-driven elements

// Non-deterministic output (differs server vs client)
Math.random()
new Date().toLocaleString()

// Safe patterns (in useEffect or state initializer)
useEffect(() => {
  // Browser APIs here are fine
}, []);

useState(() => {
  if (typeof window === "undefined") return default;
  return window.innerWidth;
});

发现 SSR 问题时，请醒目地建议使用 ssr: false 选项：

export default declareComponent(MyComponent, {
  name: "My Component",
  options: {
    ssr: false  // Disables server-side rendering
  },
});

CSS-in-JS / Tailwind / 预处理器检测

检查项目依赖项和文件，以检测样式框架：

styled-components：

• 检测：package.json 依赖项中包含 styled-components
• 要求：已安装 @webflow/styled-components-utils
• 要求：globals decorators 数组中包含 styledComponentsShadowDomDecorator

Emotion / Material UI：

• 检测：依赖项中包含 @emotion/styled、@emotion/react 或 @mui/material
• 要求：已安装 @webflow/emotion-utils
• 要求：globals decorators 数组中包含 emotionShadowDomDecorator

Tailwind CSS：

• 检测：依赖项中包含 tailwindcss
• 要求：已安装 @tailwindcss/postcss
• 要求：postcss.config.mjs 中包含 @tailwindcss/postcss 插件
• 要求：globals CSS 中导入 Tailwind（@import "tailwindcss"）

Sass：

• 检测：src 中包含 .scss 文件，或依赖项中包含 sass
• 要求：已将 sass 和 sass-loader 安装为开发依赖项
• 要求：webpack 配置中包含 .scss 规则，并使用 module.rules 函数语法
• 要求：在 webflow.json 中设置 bundleConfig

Less：

• 检测：src 中包含 .less 文件，或依赖项中包含 less
• 要求：已将 less 和 less-loader 安装为开发依赖项
• 要求：webpack 配置中包含 .less 规则，并使用 module.rules 函数语法
• 要求：在 webflow.json 中设置 bundleConfig

Webpack 配置验证规则

在 webflow.json 中指定 bundleConfig 时：

1. 指定路径下的文件必须存在
2. 必须使用 CommonJS：module.exports = { ... }
3. 以下属性会被阻止且静默忽略：entry、output、target
4. module.rules 必须是函数，而非数组：rules: (currentRules) => { ... }
5. ModuleFederationPlugin 和 MiniCssExtractPlugin 会自动去重

常见构建错误

错误	原因	修复方法
"Can't resolve '@webflow/react'"	缺少依赖项	npm i -D @webflow/react
"Cannot find module './Component'"	导入路径错误	检查相对路径
"Type 'X' is not assignable"	TypeScript 错误	修复类型不匹配
"Unexpected token"	语法错误	检查 JSX/TS 语法
"Maximum call stack"	循环导入	打破依赖循环
Bundle 超过 50MB	依赖项过多或过大	Tree-shaking、延迟加载、替换大型库
样式未显示	缺少 Shadow DOM 装饰器	添加 CSS-in-JS 装饰器，或在 .webflow.tsx 中导入样式

Bundle 大小优化

快速缩减 Bundle 大小的方法：

1. 使用生产构建：确保已启用压缩
2. Tree-shaking 导入：仅导入特定导出项
3. 替换大型库：moment → date-fns，lodash → lodash-es
4. 延迟加载：对大型组件使用动态导入
5. 检查重复项：例如多个 React 版本
6. 监控大小：Bundle 必须低于 50MB 限制