NocoBase 看板插件迎来 client-v2：无代码平台的新一代客户端架构落地

预计阅读时间：10 分钟

NocoBase 本周发布更新日志，其中最值得关注的变动是看板（Kanban）插件正式增加了 client-v2 支持。这意味着 NocoBase 正在把新一代客户端架构从核心模块逐步推向各个业务插件，看板作为高频使用的视图类型，率先完成迁移，对实际项目的影响比版本号变化更大。

client-v2 是什么，为什么看板插件要跟进

NocoBase 的 client-v2 是对原有客户端渲染层的重构版本。旧版客户端（client-v1）在插件加载、组件注册和状态管理上存在耦合较深的问题——每个插件的 UI 组件直接挂载到全局上下文，导致插件间相互干扰、热更新困难、打包体积膨胀。

client-v2 的核心变化：

插件隔离加载：每个插件拥有独立的组件注册表，不再污染全局命名空间。
按需渲染：视图组件只在被实际访问时才加载，减少首屏资源。
统一的 Schema 驱动 UI：UI 结构通过 JSON Schema 描述，插件只需声明 Schema 节点，框架负责渲染。

看板插件是 NocoBase 中使用频率最高的视图插件之一（和表格、日历并列）。把它迁移到 client-v2，等于在最常见的用户交互场景里验证了新架构的可行性，也为后续其他插件的迁移提供了参考路径。

版本分支与安装选择

NocoBase 目前维护三个分支，理解它们的定位才能决定用哪个版本拿到看板插件的 client-v2 支持：

分支	定位	看板 client-v2 状态
`main`	最稳定版本，推荐生产安装	尚未包含，需等待合并
`next`	即将发布的新功能，经过初步测试	✅ 已包含
`develop`	开发分支，功能最前沿但未充分测试	✅ 已包含，可能不稳定

如果你现在就想体验看板的 client-v2，应选择 next 分支。生产环境建议等 main 分支合并后再升级。

实际部署：用 Docker 快速跑一个带看板 client-v2 的 NocoBase

以下示例用 Docker Compose 启动 NocoBase next 分支，并创建一个包含看板视图的集合。你可以直接复制运行，只需改掉管理员密码。

# docker-compose.yml
version: "3.8"
services:
  app:
    image: nocobase/nocobase:next
    ports:
      - "13000:80"
    environment:
      - NOCOBASE_ENV=next
      - ADMIN_PASSWORD=changeme123   # ← 改成你的密码
      - DB_HOST=db
      - DB_PORT=5432
      - DB_USER=nocobase
      - DB_PASSWORD=nocobase_pwd
      - DB_DATABASE=nocobase
    depends_on:
      db:
        condition: service_healthy
    volumes:
      - nocobase_storage:/app/storage

  db:
    image: postgres:16-alpine
    environment:
      - POSTGRES_USER=nocobase
      - POSTGRES_PASSWORD=nocobase_pwd
      - POSTGRES_DB=nocobase
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U nocobase"]
      interval: 5s
      timeout: 3s
      retries: 10
    volumes:
      - nocobase_db:/var/lib/postgresql/data

volumes:
  nocobase_storage:
  nocobase_db:

启动命令：

# 启动服务
docker compose up -d

# 等待约 30 秒后检查健康状态
docker compose ps

# 查看日志确认 client-v2 插件加载
docker compose logs app | grep -i "client-v2"

启动完成后访问 http://localhost:13000，用设置的管理员密码登录。

配置看板视图：Schema 方式 vs 旧版方式对比

client-v2 下，看板视图的配置通过 Schema 声明。下面展示如何用 NocoBase 的 API 创建一个任务看板，按状态字段分组：

# 1. 先登录获取 token（替换密码为你实际设置的值）
TOKEN=$(curl -s -X POST http://localhost:13000/api/auth:signIn \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@nocobase.com","password":"changeme123"}' \
  | python3 -c "import sys,json; print(json.load(sys.stdin)['data']['token'])")

# 2. 创建集合：任务表，包含 title 和 status 字段
curl -s -X POST http://localhost:13000/api/collections \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "tasks",
    "fields": [
      {"name": "title", "type": "string"},
      {"name": "status", "type": "string", "interface": "select",
       "options": {
         "choices": [
           {"value": "todo", "label": "待办", "color": "#gray"},
           {"value": "in_progress", "label": "进行中", "color": "#blue"},
           {"value": "done", "label": "已完成", "color": "#green"}
         ]
       }
      }
    ]
  }' | python3 -m json.tool

# 3. 创建看板视图（client-v2 Schema 方式）
curl -s -X POST http://localhost:13000/api/uiSchemas:bulkCreate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "schema": {
      "type": "void",
      "x-component": "Kanban",
      "x-component-props": {
        "collection": "tasks",
        "groupField": "status",
        "cardFields": ["title", "status"],
        "dragSort": true
      },
      "properties": {
        "todo": {"type": "void", "x-component": "Kanban.Column", "x-component-props": {"value": "todo"}},
        "in_progress": {"type": "void", "x-component": "Kanban.Column", "x-component-props": {"value": "in_progress"}},
        "done": {"type": "void", "x-component": "Kanban.Column", "x-component-props": {"value": "done"}}
      }
    }
  }' | python3 -m json.tool

关键差异在于第三步：旧版客户端需要在前端 UI 中手动配置视图，配置数据散落在多个 API 中；client-v2 的 Schema 方式把整个视图结构一次性声明，包括分组字段、卡片展示字段、拖拽排序等行为参数，全部集中在 x-component-props 里。这样做的好处：

视图配置可以版本化管理，随代码仓库一起追踪变更。
迁移和复制视图只需导出/导入一段 JSON，不再依赖前端操作。
插件升级时，Schema 结构比散落的配置更容易做兼容性检查。

升级注意事项与风险边界

如果你已有运行中的 NocoBase 项目并考虑升级到 client-v2 看板，需要注意以下几点：

数据兼容性：旧版看板视图的配置存储格式与 client-v2 Schema 不同。NocoBase 提供了迁移脚本，但建议先在测试环境验证：

# 在升级前备份数据库
docker compose exec db pg_dump -U nocobase nocobase > nocobase_backup_$(date +%Y%m%d).sql

# 升级后检查看板视图是否正常渲染
# 如果旧视图显示异常，运行迁移命令（next 分支内置）
curl -s -X POST http://localhost:13000/api/migrate:kanbanToClientV2 \
  -H "Authorization: Bearer $TOKEN"

插件依赖：client-v2 看板插件依赖核心的 @nocobase/client-v2 包。如果你安装了第三方插件且它们仍使用 client-v1，两套客户端架构会同时加载，增加包体积。短期内这是不可避免的过渡状态，长期 NocoBase 会逐步让所有插件迁移到 v2。

自定义扩展：如果你之前为看板写了自定义卡片组件，迁移到 client-v2 需要改写注册方式——从全局 app.components 改为插件局部注册：

// 旧版（client-v1）：全局注册
app.components['CustomKanbanCard'] = CustomCardComponent;

// 新版（client-v2）：插件内注册
import { Plugin } from '@nocobase/client-v2';

class KanbanPlugin extends Plugin {
  load() {
    this.registerComponent('CustomKanbanCard', CustomCardComponent);
  }
}

何时该跟进

场景	建议
新项目，尚未部署	直接用 `next` 分支，享受 client-v2 全部优势
生产项目，看板使用频繁	等 `main` 分支合并后升级，先在 staging 环境跑迁移验证
生产项目，看板使用不多	不急，但关注后续其他视图插件（表格、日历）的 client-v2 进展，一起升级更省事
有自定义看板扩展	立即在开发环境测试组件注册方式改写，避免升级时阻塞

NocoBase 的 client-v2 迁移是渐进式的——看板插件打头阵，后续插件会逐步跟上。对于依赖看板做项目管理的团队，现在是在测试环境验证的好时机；对于更关注平台整体稳定性的团队，等 main 分支落地再动手更稳妥。