111 lines
4.5 KiB
Markdown
111 lines
4.5 KiB
Markdown
# Next → 小程序 转化参考（详细步骤）
|
||
|
||
与 `SKILL.md` 中「Next 项目 → 小程序 最优转化方式」对应，用于按步骤执行转化。
|
||
|
||
---
|
||
|
||
## 1. 架构与目录约定
|
||
|
||
| 目录/产物 | 作用 |
|
||
|-----------|------|
|
||
| `newpp/` | Kbone 源码：多入口 React，构建输出到 `newpp/dist/mp/` |
|
||
| `miniprogram/` | 小程序壳：`app.js`、`app.json`、`custom-tab-bar`、空白页面占位等 |
|
||
| Next 根目录 `app/`、`components/` | Web 端页面与组件；可被 newpp 复制或通过 alias 引用 |
|
||
|
||
构建后：将 `newpp/dist/mp/` 下的页面与 `common/` 合并进 `miniprogram/`，保留壳的 `app.js` 全局逻辑。
|
||
|
||
---
|
||
|
||
## 2. newpp 配置
|
||
|
||
### 2.1 miniprogram.config.js
|
||
|
||
- `router`：每个页面单独 key，对应 Next 路由，**不要使用 `other` 数组**。
|
||
- 动态底部导航：`appExtraConfig` 中**不配置** `tabBar`，用自定义 React 组件 + `wx.reLaunch`。
|
||
- `global`：建议 `rem: true`、`pageStyle: true`。
|
||
- `pages`：为每个页面配置 `extra.navigationBarTitleText`。
|
||
|
||
示例（按实际路由调整）：
|
||
|
||
```javascript
|
||
router: {
|
||
index: ['/', '/(index)?', '/index.html'],
|
||
chapters: ['/chapters', '/chapters.html'],
|
||
read: ['/read/:id', '/read.html'],
|
||
my: ['/my', '/my.html'],
|
||
match: ['/match', '/match.html'],
|
||
},
|
||
appExtraConfig: {
|
||
sitemapLocation: 'sitemap.json',
|
||
// 不配置 tabBar
|
||
},
|
||
```
|
||
|
||
### 2.2 webpack.mp.config.js
|
||
|
||
- `entry`：每个页面一个入口，例如 `index`、`chapters`、`read`、`my`、`match`，指向 newpp 内对应入口 JSX。
|
||
- `isOptimize`：`const isOptimize = process.env.NODE_ENV === 'production'`，生产构建时再压缩。
|
||
- `optimization.splitChunks`：中小型项目建议 `splitChunks: false`，避免 chunk 缺失；大型项目再考虑固定命名 cacheGroups。
|
||
|
||
---
|
||
|
||
## 3. 适配层（必须）
|
||
|
||
在 newpp 内（或共享到根目录再被引用）实现：
|
||
|
||
| 文件 | 职责 |
|
||
|------|------|
|
||
| `adapters/env.js` | `isMiniProgram()`：`typeof wx !== 'undefined' && wx.getSystemInfoSync` |
|
||
| `adapters/request.js` | Web：`fetch`；小程序：`wx.request`，统一返回 Promise |
|
||
| `adapters/storage.js` | Web：`localStorage`；小程序：`wx.getStorageSync`/`setStorageSync` |
|
||
| `adapters/router.js` | Web：`window.location` 或 Next Router；小程序：`wx.navigateTo`/`wx.reLaunch`，路径用 `toMpPath(path)` 转成小程序页面路径 |
|
||
|
||
业务代码**只**通过适配层访问请求、存储、路由，不直接使用 `window`、`document`、`localStorage`、`URLSearchParams` 等。
|
||
|
||
---
|
||
|
||
## 4. 功能控制一致
|
||
|
||
与 Next 端保持一致：
|
||
|
||
- 功能开关来自同一 API，例如 `/api/db/config` 的 `features.matchEnabled`。
|
||
- 底部导航「找伙伴」等入口根据该配置条件渲染，不在小程序端写死。
|
||
- 支付方式、营销二维码等同样由 API 配置驱动，两端逻辑一致。
|
||
|
||
---
|
||
|
||
## 5. UI 来源策略
|
||
|
||
- **复制适配**：从 Next 的 `app/**/page.tsx`、`components/**` 复制到 newpp，改为 JSX，用适配层替代 `Link`/`useRouter`/`usePathname`/`fetch`。
|
||
- **Alias 引用**：在 newpp 的 webpack `resolve.alias` 中指向项目根目录的共享组件目录，保证该目录内仅用 React + 适配层，无 Next 专属 API。
|
||
|
||
---
|
||
|
||
## 6. 样式兼容（与 Next 视觉一致）
|
||
|
||
- **Grid → Flex**：所有 Grid 布局改为 Flex，并加 `boxSizing: 'border-box'`、必要时 `lineHeight`。
|
||
- **backdrop-filter / sticky**：不支持则用纯色、渐变或占位，保证布局不错位。
|
||
- **单位**：小程序侧可用 rpx，与 Web 的 rem/px 按设计稿统一换算。
|
||
|
||
详见 `troubleshooting.md` 中的「样式问题」小节。
|
||
|
||
---
|
||
|
||
## 7. 构建与合并流程
|
||
|
||
1. 在 newpp 执行：`NODE_ENV=production npm run build:mp`。
|
||
2. 将 `newpp/dist/mp/` 下生成的页面目录及 `common/` 复制/合并到 `miniprogram/`。
|
||
3. 保留 miniprogram 壳的 `app.js`（全局 data、onLaunch、onShow 等），仅覆盖或新增 Kbone 生成的页面与 common。
|
||
4. 用微信开发者工具打开 `miniprogram/` 根目录，编译并测试。
|
||
|
||
---
|
||
|
||
## 8. 检查清单
|
||
|
||
- [ ] miniprogram.config.js：每页单独 router，无 `other`；未配置原生 tabBar。
|
||
- [ ] webpack.mp.config.js：每页有 entry；isOptimize 按 NODE_ENV；中小型项目 splitChunks 为 false。
|
||
- [ ] 适配层：env、request、storage、router 已实现并在业务中统一使用。
|
||
- [ ] 功能开关与 Next 一致，来自同一 API。
|
||
- [ ] 样式：无 Grid，Flex 已加 boxSizing/lineHeight；不支持特性已替代。
|
||
- [ ] 合并后 app.js 未被错误覆盖，页面路径与 app.json 一致。
|