常见问题

本篇介绍一些常见的问题，会持续更新。

1. 修改 pages.json、manifest.json 被覆盖问题

• pages.json

本项目引入了 @uni-helper/vite-plugin-uni-pages，pages.json 文件将会自动生成，手动修改 pages.json 将会被覆盖。

全局的东西请在 pages.config.ts 里面配置，页面的东西请在 vue 文件的 route-block 配置。

• manifest.json

与上面类似。本项目引入了 @uni-helper/vite-plugin-uni-manifest，manifest.json 文件将会自动生成，手动修改 manifest.json 将会被覆盖。

如需修改，请在 manifest.config.ts 里面修改。

详情请见uni 插件篇

2. 如何设置/修改首页？

vue 文件的 route-block 块里面设置 type="home" 即可，请确保项目里面 只有一个页面 是这个配置。

注意：如果有多个，会按照字母顺序排列，第一个是首页。（可能不是您的想要的效果。）

3. 怎么分包？

vite.config.ts 里面有一个配置，如下：(其中 subPackages 就是用来分包的)

UniPages({
    exclude: ['**/components/**/**.*'],
    subPackages: ['src/pages-sub'], // 是个数组，可以配置多个
}),

4. 首次运行 pnpm:mp 时报错。

首次运行 pnpm:mp 时报错，报错如下：

Error: ENOENT: no such file or directory, open '/Users/burtlai/unibest-projects/unibest/src/manifest.json'

首次运行 非h5端 时都可能出现上面的问题，需要先执行一下 pnpm i 以生成 src/manifest.json 文件，后面就不会报错了。

5. git commit 报错。

请看 commitlint.config.ts 里面的配置，需要满足对应的设定。根据自己的需要，可以修改 commitlint.config.ts 里面的配置。

如果是一次的（比如引入了某个第三方库），可以通过 --no-verify 参数跳过校验：

git commit -m "feat: xxx" --no-verify

第三方库还有另外一种处理方式，放到特定的文件夹，然后在 .eslintignore 和 .styleintignore 里面加上该文件夹。

6. 不想要严格的 git 提交检测，怎么办？

直接把 .husky 这个文件删掉即可。(或者不删除，只把里面的文件内容注释掉。)

7. uni-app 无法使用 process.env 变量，怎么办？

使用 import.meta.env 替代！

8. 如何跟随 uni-app 官方升级？

项目下，执行 npx @dcloudio/uvm@latest 即可更新。

注意，上面的命令会自动安装 vue-i18n，可以手动删除（pnpm un vue-i18n)，也可以不理它（没多大影响）。

9. 如何把已经加入 git 管理的文件移出 git 管理?

• 第一步，先把文件移出git 管理，操作如下：

# git rm -r --cached file1 file2  ## 针对某些文件
# git rm -r --cached dir1 dir2  ## 针对某些文件夹
# git rm -r --cached .  ## 针对所有文件

• 第二步，提交 commit 以正式删除的文件

总结：git rm -r --cached . + git commit 即可。

10. 支付宝小程序运行报错。

• 默认运行是会报错的，如下图

• 只需要勾上 本地开发跳过 ES5 转译 即可正常运行，如下图

总结：勾上 本地开发跳过 ES5 转译 即可。

11. 支持 uni-app x 吗？

不支持。但我们一直保持关注。uni-app x 传送门

目前 unibest 已经有 hbx 模板，后续接入 uni-app x 会很容易，坐等官方发布。

12. 为啥 package.json 中 vue 已经 3.4+ 了，还不支持 defineModel ?

uni-app 官方虽然已经把 vue 升级到 3.4+ 了，但是目前只有 H5端 支持 defineModel，其他端目前运行报错，详情请看 uni-app 官网的发布日志：

HBuilder X - Release Notes

关键截图如下：（仅支持 H5端）

真实运行报错截图如下：（分别是 小程序 和 APP， 都会报错 ）

13. base 模板如何接 uniCloud ?

• 1. 操作方案：直接在原始项目目录上右键（就是导入整个 unibest 项目文件夹），重新识别项目类型，就可以关联 uniCloud 了，然后用原始项目直接运行就可以了，不需要再 pnpm dev:app 后导入 dist/dev/app 再运行了。
• 2. 问：其他模板可以吗？答：其他模板也可以，操作同上。
• 3. 我写的文章链接：【unibest】可以去掉 hbx 模版了，base 模板一统天下

14. 微信小程序编译报错

[ WXSS 文件编译错误]
./app.wxss(61:2204): unexpected `\` at pos 5292(env: macOS,mp,1.06.2412040; lib: 3.7.12)

大概率是因为 node 版本比较低(比如 v18), 只需要把 node版本升级到 v22+ 就行。(已经有多为同学遇到，可能是因为微信开发者工具升级导致的，升级后就可以了。)

如果上面还不行，则把微信开发者工具版本回退到 1.06.2503290。

还有一个可能性，今天群里反馈的（2025-06-21）：

暂不确定是哪个包小版本有问题，使用 unibest 模板里面的 lock 文件就可以，自己安装就有问题（稳定复现）。

如果还是有问题，建议试试使用我模板里面的 lock 文件，我模板里面的 lock 文件是稳定的。

15. ios 模拟器运行报错

14:20:36.428 编译器版本：4.66（vue3）
14:20:36.428 正在编译中...
14:20:38.259 ✘ [ERROR] Cannot start service: Host version "0.20.2" does not match binary version "0.25.5"
14:20:38.259 1 error
14:20:38.264 failed to load config from /Users/burtlai/unibest-projects/unibest/vite.config.ts
14:20:38.264 error during build:
14:20:38.264 Error: The service was stopped
14:20:38.264     at /Users/burtlai/unibest-projects/unibest/node_modules/.pnpm/esbuild@0.20.2/node_modules/esbuild/lib/main.js:1084:25
14:20:38.264     at responseCallbacks.<computed> (/Users/burtlai/unibest-projects/unibest/node_modules/.pnpm/esbuild@0.20.2/node_modules/esbuild/lib/main.js:704:9)
14:20:38.264     at Socket.afterClose (/Users/burtlai/unibest-projects/unibest/node_modules/.pnpm/esbuild@0.20.2/node_modules/esbuild/lib/main.js:694:28)
14:20:38.265     at Socket.emit (node:events:536:35)
14:20:38.265     at endReadableNT (node:internal/streams/readable:1698:12)
14:20:38.265     at process.processTicksAndRejections (node:internal/process/task_queues:90:21)
14:20:38.276 已停止运行...

把 package.json 中的 esbuild 版本改为 0.20.2 即可。

16. pnpm i 报错

pnpm 9 + node 18 目前出现以下问题：ERR PNPM INVALID WORKSPACE CONFIGURATIoN packages field missing or empty

群友说：node 22 没有问题。原话如下：我昨天也是这样，pnpm9+node18，今天升级到node22就好了，没有动pnpm。

如果还不行，那就把 pnpm 升级到 pnpm 10。

全文完~