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。

示例（按实际路由调整）：

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. 构建与合并流程

在 newpp 执行：NODE_ENV=production npm run build:mp。
将 newpp/dist/mp/ 下生成的页面目录及 common/ 复制/合并到 miniprogram/。
保留 miniprogram 壳的 app.js（全局 data、onLaunch、onShow 等），仅覆盖或新增 Kbone 生成的页面与 common。
用微信开发者工具打开 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 一致。

4.5 KiB Raw Blame History Unescape Escape

Next → 小程序 转化参考（详细步骤）