soul-yongping/.cursor/skills/kbone-miniprogram

Kbone 小程序开发技能

概述

这个技能帮助 AI Agent 更好地处理使用 Kbone 框架将 React Web 应用转换为微信小程序的任务。

适用场景：

• 配置 Kbone 项目
• 优化 Kbone 构建
• 解决跨平台兼容性问题
• 排查 Kbone 相关错误

---

文件说明

SKILL.md

主要技能文档，包含：

• Kbone 核心配置规范
• 常见问题快速解决方案
• 跨平台适配层设计
• 开发流程和最佳实践
• 快速检查清单

reference.md

Next → 小程序转化参考（详细步骤），包含：

• 架构与 newpp 配置、适配层、功能控制一致
• 底部菜单必须用自定义组件（不要用原生 tabBar）
• UI 来源策略、样式兼容、安全区与标题/胶囊避让
• 构建与合并流程、检查清单

troubleshooting.md

详细的故障排查指南，包含：

• 从 Next 迁移要点、编译问题（chunk 文件、Babel、依赖）
• 运行时问题（URLSearchParams、localStorage、window/document）
• 样式问题（Grid、盒模型、标题/头部被胶囊或电池栏遮挡、Flexbox）
• 路由问题（导航、switchTab、动态路由）
• 网络问题（API 请求、跨域）
• 性能问题（加载慢、卡顿）
• 调试技巧和工具

---

技能使用指南

何时使用此技能

Agent 应该在以下情况下自动应用此技能：

1. 项目配置

   • 用户提到 "kbone"、"小程序"、"miniprogram"
   • 需要配置 miniprogram.config.js
   • 需要配置 webpack.mp.config.js

2. 代码转换

   • 将 React Web 应用转换为小程序（含 Next 项目转化）
   • 需要创建跨平台适配层
   • 处理 Web 和小程序的 API 差异
   • 底部菜单保留自定义组件（不要用原生 tabBar）、安全区与标题避让

3. 问题排查

   • 编译错误（chunk 文件、Webpack 配置）
   • 运行时错误（API 不兼容）
   • 样式问题（Grid、布局错乱）
   • 路由问题（导航失败）

4. 优化任务

   • 优化 Kbone 配置
   • 减小包体积
   • 提升性能

---

核心知识点

1. 配置规范

router 配置：每个页面单独配置

router: {
  index: ['/', '/index.html'],
  my: ['/my', '/my.html'],
}

pages 配置：每个页面设置标题

pages: {
  index: {
    extra: { navigationBarTitleText: '首页' }
  }
}

---

2. 兼容性处理

必须避免的 API：

• URLSearchParams（自定义实现）
• localStorage（使用适配器）
• window、document（条件使用）

必须避免的 CSS：

• CSS Grid（改用 Flexbox）
• 未设置 box-sizing: border-box

---

3. 代码分割策略

中小型项目（<20 页面）：

splitChunks: false // 禁用，优先稳定性

大型项目（>50 页面）：

splitChunks: { chunks: 'all' } // 启用，优化体积

---

4. 环境判断

function isMiniProgram() {
  return typeof wx !== 'undefined' && wx.getSystemInfoSync
}

---

快速参考

常见问题速查

问题	文档位置
redirect 跳转异常（用了 home）	SKILL.md > 必记坑点 1 / troubleshooting.md > 配置问题 1
Babel 报错（?. / ??）	SKILL.md > 必记坑点 2 / troubleshooting.md > 编译问题 2
chunk 文件缺失	SKILL.md > 问题 2
URLSearchParams 错误	SKILL.md > 问题 3 / troubleshooting.md > 运行时问题 1
CSS Grid 不生效	SKILL.md > 问题 1 / troubleshooting.md > 样式问题 1
底部菜单/导航（不要用原生 tabBar）	SKILL.md > 问题 4 / reference.md > 4.5
安全区/标题被胶囊或电池栏遮挡	reference.md > 第 7 节 / troubleshooting.md > 样式问题 4
阅读页上下章/数据源	SKILL.md > 必记坑点 3、4
页面跳转失败	troubleshooting.md > 路由问题 1
API 请求失败	troubleshooting.md > 网络问题 1

---

配置文件速查

配置	文件	关键点
路由配置	miniprogram.config.js	router 每个页面单独配置
页面标题	miniprogram.config.js	pages 配置 navigationBarTitleText
代码分割	webpack.mp.config.js	optimization.splitChunks
环境判断	webpack.mp.config.js	mode 和 isOptimize
入口文件	webpack.mp.config.js	entry 每个页面一个入口

---

使用示例

场景 1：配置新项目

用户消息：

"帮我配置一个 kbone 项目，有首页、目录、阅读三个页面"

Agent 应该：

1. 读取 SKILL.md
2. 创建 miniprogram.config.js，配置 router 和 pages
3. 创建 webpack.mp.config.js，配置 entry 和 optimization
4. 创建跨平台适配器（router、request、storage、env）
5. 提供构建和测试命令

---

场景 2：修复编译错误

用户消息：

"编译报错：ENOENT: no such file or directory, open '.../defaultchaptersindex.js'"

Agent 应该：

1. 识别为 chunk 文件缺失问题
2. 读取 SKILL.md > 问题 2 或 troubleshooting.md > 编译问题 1
3. 判断项目规模
4. 禁用或配置 splitChunks
5. 重新构建并验证

---

场景 3：修复运行时错误

用户消息：

"小程序报错：URLSearchParams is not defined"

Agent 应该：

1. 识别为 API 兼容性问题
2. 读取 SKILL.md > 问题 3 或 troubleshooting.md > 运行时问题 1
3. 创建 buildQueryString 函数
4. 替换所有 URLSearchParams 使用
5. 测试验证

---

场景 4：优化配置

用户消息：

"根据 kbone 官方文档优化我的配置"

Agent 应该：

1. 读取 SKILL.md > 核心配置规范
2. 检查 router、pages、global 配置
3. 检查 webpack mode 和 isOptimize
4. 优化不规范的配置
5. 提供优化说明和测试指引

---

维护说明

更新触发条件

当以下情况发生时，应更新此技能：

1. Kbone 官方更新

   • 新版本配置变化
   • 新增功能或 API
   • 废弃旧配置

2. 发现新问题

   • 遇到新的兼容性问题
   • 发现新的最佳实践
   • 用户反馈的常见问题

3. 项目实践积累

   • 新的解决方案
   • 更好的配置策略
   • 优化的代码模式

---

更新流程

1. 在 troubleshooting.md 添加新问题和解决方案
2. 如果是常见问题，在 SKILL.md 添加快速方案
3. 更新本 README.md 的快速参考表
4. 在项目 开发文档/8、部署/ 下创建详细文档

---

参考资源

官方文档

• Kbone 官方文档
• React 项目模板
• 小程序官方文档

项目文档

项目 开发文档/8、部署/ 目录下有详细的实践文档：

• Kbone配置优化说明.md
• 小程序样式修复说明.md
• 自定义导航组件方案.md
• API接入说明.md
• Webpack代码分割问题修复.md

---

反馈与改进

如果在使用过程中发现：

• 文档不清楚的地方
• 缺少的问题和解决方案
• 更好的实践方法

请更新相应的文档文件，保持技能的时效性和准确性。