AI Agent 课程文档

切换日光/暗黑模式

089. 发包、Demo 工程与扩展验证 ​

学习目标 ​

这一节把通用表格包发布出去，并在一个新工程里验证扩展能力。

学完后，你应该能理解：

  • 发布 npm 包前要确认哪些配置；
  • 为什么 npm registry 要切到官方地址；
  • npm 发布为什么需要登录和二次验证；
  • 新工程为什么还要安装组件库的外部依赖；
  • 如何在新工程里接入通用表格；
  • 如何扩展表格模块；
  • 如何扩展一个颜色选择列；
  • 模块顺序为什么会影响运行。

发布前确认 registry ​

发布 npm 包前，要确认当前 npm registry 指向官方 npm。

如果你平时使用国内镜像，发布会失败。

可以用 nrm 之类工具切换源。

发布公开包时，要保证命令最终发到 npm 官方仓库。

否则你以为发布了，实际可能只是请求了镜像地址。

npm 登录与二次验证 ​

发布包前需要登录 npm。

如果账号开启了 2FA，还要输入一次性验证码。

现在 npm 发布限制越来越严格。

原因是包投毒事件很多。

如果开发者 token 泄露，攻击者可能发布恶意版本。

所以正式发包流程里，认证、版本、发布来源都很重要。

版本不能重复 ​

公开 npm 包同一个版本只能发布一次。

如果 0.0.15 已经发布过，再发布同版本会失败。

要重新发布，就必须修改版本号。

例如改成：

json
{
  "version": "0.0.16"
}

然后重新打包和发布。

包入口要和产物一致 ​

这一节里遇到过包安装后找不到入口的问题。

根因是 package.json 里写的入口文件名和 dist 里的真实产物不一致。

例如配置指向：

json
"module": "dist/main.js"

那打包产物里就必须真的有 main.js。

如果打包产物叫别的名字，安装后使用者项目会报包不存在或入口找不到。

这是组件库发包时很常见的问题。

新建 Demo 工程 ​

包发布后，需要在另一个干净工程里验证。

这样才能确认：

  • 包能被 npm 安装；
  • 入口导出正确；
  • 类型声明可用；
  • 样式能加载；
  • 外部依赖是否缺失；
  • 扩展机制是否跨项目生效。

只在原项目里测试不够。

因为原项目里很多路径和依赖都是本地可见的。

新工程能暴露真实使用问题。

安装组件包 ​

在 Demo 工程里，像安装普通依赖一样安装组件包。

例如：

bash
npm install @peryl/agent

安装后，package.json 会出现这个依赖。

如果刚发布的版本 npm 还没立刻同步出来，可以稍等一下。

npm 页面和实际安装之间可能有短暂延迟。

为什么还要装外部依赖 ​

组件包打包时把一些依赖排除掉了。

例如：

  • React；
  • Ant Design；
  • Ant Design X；
  • dayjs；
  • 其他组件库依赖。

这些依赖不会被打进包产物。

所以 Demo 工程也要安装它们。

否则运行时会报找不到依赖。

这是组件库常见设计。

React 这类基础库通常应该由使用者项目提供，而不是组件库自己打包一份。

接入 ConfigProvider ​

Demo 工程里需要接入 Ant Design 的 ConfigProvider。

它负责给组件提供主题、语言、前缀等上下文。

如果组件库内部使用 Ant Design，外层应用也要准备好 Ant Design 运行环境。

这和普通业务项目里使用 Ant Design 是一样的。

接入请求服务 ​

通用表格需要请求后端数据。

请求里需要 token。

所以 Demo 工程里要设置一个可用 token。

课程里把 token 服务导出后，可以在 Demo 工程里直接设置测试 token。

这样表格请求后端时能通过认证。

如果没有 token，就会请求失败。

后端地址 ​

Demo 工程要配置后端地址。

可以指向本地后端。

也可以指向已部署的服务器后端。

如果要用服务器后端，需要先完成后端发版。

如果仓库地址换过，发版脚本里也要更新仓库地址，并清理旧目录里的 .git 信息。

否则脚本可能继续拉旧仓库。

验证基础表格功能 ​

接入组件包后，要先验证基础功能。

例如：

  • 数据能加载；
  • 表格能显示；
  • 行能进入编辑状态；
  • 保存能请求后端；
  • 保存后数据能更新；
  • 分页能工作。

这些基础功能通过后，再验证扩展能力。

否则扩展报错时，很难判断是包本身、依赖、后端还是扩展代码的问题。

扩展默认配置类型 ​

Demo 工程可以扩展组件包里的类型。

例如给默认配置增加一个标题字段：

ts
declare module "@peryl/agent" {
  interface AutoTableDefaultConfig {
    autoTableTitle?: string
  }
}

扩展后，在表格配置里就能填写这个字段。

没有类型扩展时，TypeScript 会提示这个字段不存在。

新增表格模块 ​

Demo 工程可以通过模块注册器添加模块。

例如读取 autoTableTitle，再通过 bodyRender 往表格主体区域插入一段标题或公告。

模块逻辑大致是：

ts
autoTable.hooks.bodyRender.use({
  seq: 2.5,
  key: "autoTableTitle",
  content: <Alert message={title} />,
})

seq: 2.5 表示它插入在搜索栏和筛选条件展示之间。

这说明外部项目可以不改组件源码，就往表格内部加内容。

覆盖默认模块 ​

如果注册同名模块，就可以覆盖默认模块。

例如用同一个 queryForm key 注册一个空模块。

这样默认查询表单就不会执行。

取消覆盖后，查询表单又会恢复。

这证明模块注册器能支持不同项目对同一组件的差异化需求。

页面级添加内容 ​

除了写模块，也可以在当前页面直接操作渲染钩子。

例如在页面里拿到 autoTable 后，直接往 bodyRender 里加按钮。

这种方式只影响当前页面。

如果希望每个页面都生效，就应该封装成模块，在创建表格 Hook 时统一注册。

判断方式很简单：

  • 只当前页面需要：页面里直接加；
  • 多个页面复用：封装成模块。

扩展颜色选择列 ​

这一节还演示了新增颜色选择列。

流程和图片列类似：

  1. 在 Demo 工程里定义颜色列类型；
  2. 通过声明合并扩展组件包的列类型；
  3. 注册颜色列默认值；
  4. 使用 Ant Design 的 ColorPicker 作为编辑组件；
  5. 在页面列配置里使用 type: "color"。

这样就能在外部项目里新增一个组件库原本没有的列类型。

导出类型也很重要 ​

扩展颜色列时，遇到过某个类型没有从包入口导出的问题。

这会导致 Demo 工程无法引用扩展所需类型。

解决方式是回到组件库入口文件，把需要外部使用的类型导出。

然后重新打包、改版本、发布。

这提醒我们：组件库不只要导出组件，也要导出扩展所需的类型和工具。

ColorPicker 的值格式 ​

颜色选择器的值不一定直接是字符串。

有些组件的 onChange 返回对象。

如果后端字段需要保存字符串，就要在编辑组件里做转换。

例如把颜色对象转成十六进制字符串。

这类问题很常见。

通用表格列扩展时，要特别注意组件值格式和后端字段格式是否一致。

模块顺序很重要 ​

模块之间有依赖关系。

例如事件模块需要调用状态模块提供的方法。

状态模块需要读取配置模块提供的运行配置。

所以顺序不能乱。

如果依赖的模块还没有安装，就会在读取属性时出错。

没有依赖关系的模块可以使用相同 seq。

有依赖关系的模块必须保证依赖先执行。

后端接口也可以抽象 ​

课程最后提到，通用表格现在对接的是通用后端接口。

但真实项目可能有各种接口风格。

例如：

  • 查询接口路径不同；
  • 新增接口路径不同；
  • 删除接口路径不同；
  • 请求参数结构不同；
  • 需要签名或额外 header。

更完整的做法是抽象一层接口适配器。

使用者只要实现约定的方法。

通用表格不关心你内部怎么请求。

它只关心你能不能提供查询、新增、更新、删除等能力。

这一节的核心 ​

这一节完成了从“组件库内部可扩展”到“外部项目可扩展”的验证。

关键链路是：

  • 发布 npm 包；
  • 新工程安装包；
  • 补齐外部依赖；
  • 配置请求 token；
  • 验证基础表格；
  • 添加自定义表格模块；
  • 覆盖默认模块；
  • 扩展颜色选择列；
  • 修复包入口和类型导出问题。

通用组件真正可复用，不只是能打包。

更重要的是：外部项目能在不改源码的情况下，添加自己的功能和类型。

AI Agent 课程学习文档。

Copyright © 2026