268 lines
6.1 KiB
Markdown
268 lines
6.1 KiB
Markdown
# Kbone 小程序开发技能
|
||
|
||
## 概述
|
||
|
||
这个技能帮助 AI Agent 更好地处理使用 Kbone 框架将 React Web 应用转换为微信小程序的任务。
|
||
|
||
**适用场景**：
|
||
- 配置 Kbone 项目
|
||
- 优化 Kbone 构建
|
||
- 解决跨平台兼容性问题
|
||
- 排查 Kbone 相关错误
|
||
|
||
---
|
||
|
||
## 文件说明
|
||
|
||
### SKILL.md
|
||
主要技能文档，包含：
|
||
- Kbone 核心配置规范
|
||
- 常见问题快速解决方案
|
||
- 跨平台适配层设计
|
||
- 开发流程和最佳实践
|
||
- 快速检查清单
|
||
|
||
### troubleshooting.md
|
||
详细的故障排查指南，包含：
|
||
- 编译问题（chunk 文件、Babel、依赖）
|
||
- 运行时问题（URLSearchParams、localStorage、window/document）
|
||
- 样式问题（Grid、盒模型、Flexbox）
|
||
- 路由问题（导航、switchTab、动态路由）
|
||
- 网络问题（API 请求、跨域）
|
||
- 性能问题（加载慢、卡顿）
|
||
- 调试技巧和工具
|
||
|
||
---
|
||
|
||
## 技能使用指南
|
||
|
||
### 何时使用此技能
|
||
|
||
Agent 应该在以下情况下自动应用此技能：
|
||
|
||
1. **项目配置**
|
||
- 用户提到 "kbone"、"小程序"、"miniprogram"
|
||
- 需要配置 `miniprogram.config.js`
|
||
- 需要配置 `webpack.mp.config.js`
|
||
|
||
2. **代码转换**
|
||
- 将 React Web 应用转换为小程序
|
||
- 需要创建跨平台适配层
|
||
- 处理 Web 和小程序的 API 差异
|
||
|
||
3. **问题排查**
|
||
- 编译错误（chunk 文件、Webpack 配置）
|
||
- 运行时错误（API 不兼容）
|
||
- 样式问题（Grid、布局错乱）
|
||
- 路由问题（导航失败）
|
||
|
||
4. **优化任务**
|
||
- 优化 Kbone 配置
|
||
- 减小包体积
|
||
- 提升性能
|
||
|
||
---
|
||
|
||
## 核心知识点
|
||
|
||
### 1. 配置规范
|
||
|
||
**router 配置**：每个页面单独配置
|
||
```javascript
|
||
router: {
|
||
index: ['/', '/index.html'],
|
||
my: ['/my', '/my.html'],
|
||
}
|
||
```
|
||
|
||
**pages 配置**：每个页面设置标题
|
||
```javascript
|
||
pages: {
|
||
index: {
|
||
extra: { navigationBarTitleText: '首页' }
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 2. 兼容性处理
|
||
|
||
**必须避免的 API**：
|
||
- `URLSearchParams`（自定义实现）
|
||
- `localStorage`（使用适配器）
|
||
- `window`、`document`（条件使用）
|
||
|
||
**必须避免的 CSS**：
|
||
- CSS Grid（改用 Flexbox）
|
||
- 未设置 `box-sizing: border-box`
|
||
|
||
---
|
||
|
||
### 3. 代码分割策略
|
||
|
||
**中小型项目**（<20 页面）：
|
||
```javascript
|
||
splitChunks: false // 禁用，优先稳定性
|
||
```
|
||
|
||
**大型项目**（>50 页面）：
|
||
```javascript
|
||
splitChunks: { chunks: 'all' } // 启用，优化体积
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 环境判断
|
||
|
||
```javascript
|
||
function isMiniProgram() {
|
||
return typeof wx !== 'undefined' && wx.getSystemInfoSync
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 快速参考
|
||
|
||
### 常见问题速查
|
||
|
||
| 问题 | 文档位置 |
|
||
|------|---------|
|
||
| chunk 文件缺失 | SKILL.md > 问题 2 |
|
||
| URLSearchParams 错误 | SKILL.md > 问题 3 / troubleshooting.md > 运行时问题 1 |
|
||
| CSS Grid 不生效 | SKILL.md > 问题 1 / troubleshooting.md > 样式问题 1 |
|
||
| 底部导航动态显示 | SKILL.md > 问题 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 '.../default~chapters~index.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 官方文档](https://wechat-miniprogram.github.io/kbone/docs/)
|
||
- [React 项目模板](https://github.com/wechat-miniprogram/kbone-template-react)
|
||
- [小程序官方文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
|
||
|
||
### 项目文档
|
||
项目 `开发文档/8、部署/` 目录下有详细的实践文档：
|
||
- Kbone配置优化说明.md
|
||
- 小程序样式修复说明.md
|
||
- 自定义导航组件方案.md
|
||
- API接入说明.md
|
||
- Webpack代码分割问题修复.md
|
||
|
||
---
|
||
|
||
## 反馈与改进
|
||
|
||
如果在使用过程中发现：
|
||
- 文档不清楚的地方
|
||
- 缺少的问题和解决方案
|
||
- 更好的实践方法
|
||
|
||
请更新相应的文档文件，保持技能的时效性和准确性。
|