Appearance
常见问题
FAQ
常见问题
这里整理接入组件库和文档维护时最常见的问题。遇到业务组件异常时，优先检查环境、登录态、接口权限和事件协议。
安装 @mbjia/* 包失败
检查 .npmrc：
ini
@mbjia:registry=http://verdaccio.atvideo.cc
registry=https://registry.npmmirror.com/检查 hosts：
txt
47.103.41.64 verdaccio.atvideo.cc业务组件无法正常请求
检查：
- 是否已登录。
- Cookie 中是否有 token。
@mbjia/site-env判断的环境是否正确。- 本地代理是否把
/api转发到正确后端。
上传不可用
检查：
- 浏览器是否支持
SharedWorker。 - 生产环境是否配置
sharedWorkerPath。 - OSS token 接口是否正常。
- 文件类型和大小是否通过校验。
引入 components 后主题变化
@mbjia/components 的入口会执行 AntD 全局主题配置，将主色设置为 #171436。
文档里找不到某个字段
优先检查：
- 组件源码是否真的导出了该字段。
- 字段是否来自透传的 AntD Props。
- 是否在
api/data-structures或api/services中集中说明。
如果源码中存在但文档没有，应补充对应组件页和索引页。
流程预览不显示
当前文档不依赖 Mermaid，流程图使用本地 HTML/CSS 的 flow-preview。新增流程时不要再写 mermaid 代码块，优先复用现有流程预览样式。
样式缺失或不生效
常见原因：
- Less / CSS Modules / styled-components 未正确配置构建。
- AntD 4 样式未引入。确认项目入口已
import 'antd/dist/antd.css'或类似。 @mbjia/components的全局 AntD 主题会覆盖业务项目的主题配置。
检查方法：
- 浏览器 DevTools 查看元素 class 是否生成。
- 查看
<head>中是否有 AntD 和组件的 style 标签。 - 确认构建工具（webpack/vite）支持 Less 和 CSS Modules。
接口报 401 / 403 或无权限
- 确认已登录，Cookie 中
token存在。 - 检查
@mbjia/site-env中API_ENV.host是否正确。 - 本地开发时代理是否把
/api转发到正确后端。 - 接口权限是否开通：素材、上传、AI、权益等接口可能需要单独申请。
事件没触发
- 确认
eventBus来自同一个实例（通常只需import { eventBus } from '@mbjia/utils'）。 - 检查事件名是否精确匹配（注意部分历史事件名含空格，如
global: upload-level-warning）。 - 发射事件（emit）在监听（on）之前不会触发回调，确认注册顺序。
- 查看 事件协议 确认事件方向和 payload。
组件不更新或状态异常
- 确认是否传了受控值（如
value、open），受控模式下组件不会自行更新。 - 检查是否多个素材弹窗同时存在导致状态互相覆盖。
- React 17 与 18 的并发特性可能导致部分行为差异，建议保持 React 17。
SharedWorker 不可用
- 部分浏览器（如部分移动端浏览器、旧版 Safari）不支持 SharedWorker。
- 检查控制台是否有
当前浏览器不支持SharedWorker的错误。 - 生产混剪项目需配置
process.env.sharedWorkerPath和process.env.isMbjiaMixedCutProject。 - 如果不使用上传能力，可以不引入
@mbjia/upload-manager。
版本兼容问题
- 当前组件库基于 React
~17.0.0、AntD4.24.16。React 18 或 AntD 5 项目需要额外验证。 - 使用
pnpm/yarn/npm混用安装可能导致依赖版本不一致，建议统一使用一种包管理器。 @mbjia/*各包之间有版本依赖关系，建议使用lerna bootstrap或pnpm install保持一致版本。
弹窗层级异常
- AntD Modal/Drawer 的
zIndex默认为 1000。 DropDown和Popup默认zIndex为 3002。- 业务弹窗层级异常时，检查组件的
zIndexprop 或全局ConfigProvider配置。
如何本地调试组件库
推荐方式：
bash
# 在 packages/ui 下
cd packages/ui && yarn link
# 在业务项目中
yarn link @mbjia/ui
# 调试完成后
yarn unlink @mbjia/ui && cd packages/ui && yarn unlink更多见 本地开发。