常见问题（FAQ）
常见问题（FAQ）
本页汇总 app-template、web-template、game-template 与 @htyf-mp/js-sdk 的高频问题，按“先判断、再处理”的方式整理，便于快速排障。
1) 我该选哪个模板？
Q：三种模板分别适合什么场景？
app-template：React Native 小程序，适合需要导航、Tab、原生容器能力的应用型项目。web-template：Taro + React 页面型项目，适合快速做业务页面和 H5 逻辑。game-template：Godot 游戏项目，适合玩法、物理、场景驱动型内容。
Q：我只想尽快跑通一次流程，选哪个？
优先选 web-template，改动成本最低、反馈最快。
2) 初始化与安装
Q：为什么初始化失败或覆盖了旧项目？
你可能没有在空目录执行。初始化前请确保：
- 当前目录为空，或至少不包含已有项目文件。
- 不在已有
app.json的项目根重复初始化。
Q：npm install / yarn 用哪个？
两者都可以，但同一项目建议固定一种，避免锁文件冲突。
若模板 README 写的是 yarn，优先按 README 执行。
Q：依赖安装后运行报模块缺失（ENOENT）怎么办？
优先做这三步：
- 删除
node_modules与锁文件后重新安装； - 保证 Node 版本满足文档要求（建议 Node >= 16.20.0）；
- 安装过程若有 peer 冲突，按实际错误使用对应参数重装。
3) 打包与真机调试
Q：npm run htyf 提示找不到配置或项目不合法？
通常是目录不对。请确认当前目录是“项目根”：
- 有
app.json app.json内有htyf配置
Q：扫码后打不开 / 白屏 / 资源不更新？
按顺序排查：
- 手机与电脑是否在同一局域网（或端口转发已正确配置）；
- 是否刚构建完成后再扫码；
app.json中appUrlConfig、zipUrl是否可访问；- 版本号是否已更新（避免缓存旧包）。
Q：如何区分“本地开发问题”还是“容器调试问题”？
建议流程：
- 先在本地开发环境跑通（RN/Taro/Godot 各自工具链）；
- 再进入
npm run htyf真机调试； - 若本地正常、真机异常，优先检查网络、配置地址和容器能力调用。
4) app.json 配置
Q：appUrlConfig 和 zipUrl 有什么区别？
appUrlConfig：配置/元数据入口（版本、描述、资源地址等）。zipUrl：实际资源包下载地址。
可记成：前者管“读配置”，后者管“拉代码包”。
Q：web-template 里的 webUrl 是做什么的？
webUrl 是 WebView 加载入口地址，决定打开哪个网页。
Web 项目常见是 webUrl + appUrlConfig + zipUrl 配合使用。
5) JS SDK 使用
Q：为什么 jssdk 在浏览器里调用不生效？
很多 API 依赖宿主容器，浏览器环境下不可用。建议先判断：
不在容器时走降级逻辑（如 Web 弹窗、Web 剪贴板）。
Q：最常用的 SDK API 是哪些？
- 交互：
showToast、showModal - 扫码：
openQR - 布局：
getMenuButtonBoundingClientRect、getSafeAreaInsets - 剪贴板：
setClipboardString、getClipboardString - 文件：
downloadAndSaveFile
Q：参数类型去哪里查？
直接看：
node_modules/@htyf-mp/js-sdk/dist/types/SDK.d.tsnode_modules/@htyf-mp/js-sdk/dist/types/types/options.d.ts
6) 文档与 MDX 报错
Q：为什么会出现 YAML frontmatter 解析错误？
常见原因：
description等字段里包含特殊字符但没加引号；key: value写法缺少空格或拼写错误；- frontmatter 头尾
---不完整。
建议：frontmatter 的字符串统一加双引号，尤其包含 @、:、中文标点时。
Q：改完文档后页面没更新？
- 确认 dev server 仍在运行；
- 手动刷新页面一次；
- 如缓存异常，重启
npm run dev再访问。
7) 还没解决怎么办？
请带上这三类信息再排查，效率会高很多：
- 当前模板类型（
app-template/web-template/game-template）； - 具体命令与报错原文（完整复制）；
- 当前目录关键文件（
app.json、入口文件、相关配置片段）。