uni-cms-article 客户端配置与常见问题解决
本节将 uni-CMS 的 article 端（用户端）集成到 uni-starter 项目中，并解决集成过程中遇到的一系列问题，包括 Schema 冲突、广告插件报错、AI 模块报错、JSON 配置等。这些问题在 uni-cloud 开发中非常典型，掌握排查思路对后续开发至关重要。
客户端与管理端的区别
uni-starter 默认的列表页读取的是 openDB-news-articles，而 uni-CMS article 读取的是 uni-cms-articles，两者的 Schema 并不互通。切换到 uni-CMS article 后，文章数据将由 uni-CMS 管理。
| 对比项 | openDB-news-articles | uni-cms-articles |
|---|---|---|
| 数据来源 | uni-starter 内置 | uni-CMS 管理 |
| Schema 位置 | database 根目录 | uni_modules/uni-cms |
| 管理方式 | 无专门管理后台 | uni-admin 后台管理 |
| 富文本编辑 | 不支持 | 支持，含 AI 辅助 |
安装 uni-CMS Article 插件
安装步骤
- 访问官方插件市场，找到 uni-cms-article 插件
- 点击"下载插件并导入 HBuilderX"
- 选择 uni-starter 项目（用户端）
- 确认页面注册
- 仔细检查合并内容
Schema 冲突处理
安装时最常见的坑是 Schema 重复。由于 uni_modules 中的模块会在项目根目录的 uni-cloud/database 中创建软链接，可能与已有的 Schema 重名。
解决方案：
- 对比两个同名 Schema 的内容（通常只是版本号不同）
- 删除多余的（一般是删除 uni_modules 外的那个）
- 确保每个 Schema 在 database 目录中只存在一份
pages.json 调整
安装完成后需要：
- 将 article 的列表页路径移到 pages.json 的首页位置
- 在 tabBar 配置中替换原来的列表页路径
- 在 conditions 配置中同步更新
常见问题排查
问题一：珊瑚广告插件报错
错误现象：启动后提示需要配置某个广告插件 ID。
原因：uni-CMS article 组件中默认集成了广告解锁功能（unlock-content），会加载微信小程序的珊瑚语音插件和商户运营插件。
解决方案：
找到 uni_modules/uni-cms-article/components/render-article-detail/index.vue，注释掉 unlock-content 组件：
<!-- 注释掉不需要的广告解锁功能 -->
<!-- <unlock-content ... /> -->
vue
问题二：uni-ai 模块报错
错误现象：管理端编辑文章时提示 AI 功能调用失败。
原因：未开通 uni-ai 服务。
解决方案：
找到 uni_modules/uni-cms/components/ai-chat.vue，注释掉 AI 相关代码（约 373 行的 uniAiChat.send() 调用），同时注释掉编辑页面中的 AI 助手按钮（约 59 行）。
问题三：缺少配置文件
错误现象：提示需要在 uni-CMS 中配置 clientAppid 字段。
解决方案：
在 uni-cloud/common/uni-config/ 目录下创建 uni-cms/uni-config.json：
{
"contentSecurity": {
"checkContent": "content,image"
},
"clientAppid": "你的用户端AppID",
"adUnlock": {
// 如不需要广告解锁，留空或删除
}
}
json
clientAppid 在 uni-admin 的应用管理中可以找到，对应 uni-starter 项目。
问题四：编译后文件找不到
错误现象：编译提示某个文件不存在，但实际文件是存在的。
解决方案：
- 先停止微信开发者工具
- 重新启动 HBuilderX 的调试进程
- 如果仍然不行，删除
unpackage目录后重新编译
建议：开发阶段优先使用 HBuilderX 内置浏览器调试，页面开发完成后再到小程序端调试。
问题五：quill-delta-convert 模块缺失
错误现象：控制台提示需要配置 quill-delta-convert 模块。
解决方案：
在 database 目录上右键 → 配置 schema 扩展公共模块 → 勾选 quill-delta-convert → 提交。
验证集成成功
完成所有配置后：
- 在管理端新增一篇测试文章
- 在用户端首页刷新
- 确认文章列表能正确展示 uni-CMS 的内容
- 点击文章进入详情页，确认内容正常渲染
开发调试建议
| 场景 | 推荐方式 |
|---|---|
| 页面样式开发 | HBuilderX 内置浏览器 |
| 功能联调 | 微信开发者工具 |
| 遇到缓存问题 | 删除 unpackage 重新编译 |
| Schema 冲突 | 对比内容后删除重复项 |
| 多人协作 | 每天开始前下载远端 Schema 合并 |
uni-cloud 开发的核心提醒
- Git 不可少：即使出问题也方便回滚
- Schema 同步：开发新模块前先同步远端数据
- 模块安装后检查：安装 uni_modules 插件后务必检查是否有 Schema 重复
- 调试策略：先用内置浏览器开发页面，再到小程序端调试
↑