本章收录使用过程中真实遇到的问题以及解答。每个问题都标注了问题等级——按问题领域逐组呈现。
ERR_PNPM_PEER_DEP_ISSUES现象：
原因：@lhx-kit/renderer 声明 React / Vue 为 peer dependency，你的项目没装对应框架。
修复：
模板默认已经装了，只有你是从裸项目集成时才会遇到这个问题。
lhx-kit 依赖 Node 18.18+ 的特性：
jiti@2 要求 createRequire 的现代 interop 语义@lhx-kit/offline 的 fs-extra 使用 readdir {withFileTypes}Node 17 实测偶尔能跑，但偶发 crash；Node 16 完全不兼容。请升级 Node。
pnpm-workspace.yaml 的 workspace:* 协议是 pnpm 专属。
硬要用 npm：
pnpm-workspace.yamlworkspace:* 改成文件系统路径或 npm 发包package.json#workspaces 字段)这会失去 pnpm 的硬链接 + 符号链接优势，node_modules 体积会翻倍。
experimentalMinChunkSize: 10 * 1024 是插件的默认值，目前没有对外开关。
如果你真的需要某个 chunk 不合并（比如做 A/B 测试想单独统计某个脚本大小）：
方案 1：用 /* webpackChunkName */ hint（Rollup 也支持）
即使合并，Rollup 也会把它命名成 my-special——但可能还是会被合。
方案 2：在 vite.config.ts 里覆盖
vendor-react-*.js 这么大（192KB）参考 ⚡ 性能优化 §4。简答：
brotli_static on排查步骤：
常见原因：
| 原因 | 修复 |
|---|---|
@vitejs/plugin-vue / @vitejs/plugin-react 的 .babel 转换太慢 |
用 plugin-react-swc 替换 |
| 图片资源过大 | 调 assetsInlineLimit |
| TS 严格模式 + 大量 type-check | 开 --skipLibCheck |
| node_modules 几千个包 | 考虑 optimizeDeps.include 预构建 |
| ::: |
参考 📱 移动端适配 §3.2。简答：
:::details 展开答案 原因：postcss-pxtorem 默认会转 node_modules 里的 px，把 Vant 内部坐标搞错。
修复：
Vant 自己处理了 rem 转换，不需要插件重复做。
<h1> 字体巨大Failed to resolve module specifier 'react'参考 🌐 CDN 外挂 §三。简答：
cdn.enabled = false这是正常的降级过程：
要静默：
要监控但不打扰 console：
检查 offline.config.ts 的 whitelistPages：
要让所有 page 都进：
manifest.schemaVersion = '1.0.0' 是锁死的。容器侧应该验证 schemaVersion，不同版本走不同解析逻辑。
未来计划：
:::details 展开答案 不能。see 🎨 Renderer §3.2。
替代方案：把复杂逻辑放 state：
fetchRemoteSchema 失败时返回 options.schema（本地 fallback）。确保传了：
白屏通常是因为没传 schema 参数。
@lhx-kit/config 源码后 examples 没反应workspace:* 只建软链，不自动 build。
三种解法：
日常开发用方案 2。
当前没有自动发布流程。手动步骤：
:::info 未来计划 准备接入 changesets：
:::tip 推荐顺序
实战：
lhx-cli add pagelhx-cli offline build 生成离线包
:::