调试运行时问题

此页面可帮助您解决应用成功构建但在运行时执行期间失败时的常见问题。如果您在此处找不到特定问题的解决方案，请在开发者论坛中发布问题以获得更多支持。

Metro服务器无法启动或经常崩溃

原因： 端口冲突、缓存损坏或系统资源限制。

解决方案：

1. 清除Metro缓存：

   npx react-native start --reset-cache
   

2. 检查端口冲突并使用其他端口：

   npx react-native start --port 8082
   

3. 使用详细日志记录重新启动Metro服务器：

   npx react-native start --verbose
   

4. 如果问题仍然存在，请重新启动开发计算机以清除系统资源。

应用成功构建，但在设备上不可见

原因： 应用在后台运行或存在用户界面渲染问题。

解决方案：

1. 检查哪个应用当前处于前台：

   复制代码 已复制到剪贴板。

    vlcm list
   

2. 如果您的应用处于后台，请将其置于前台：

   复制代码 已复制到剪贴板。

   vlcm trigger-app foreground -i <实例ID>
   

3. 在后台和前台之间切换以重新刷新：

   复制代码 已复制到剪贴板。

   vlcm trigger-app background -i <实例ID>
   vlcm trigger-app foreground -i <实例ID>
   

将应用置于前台后应用仍不可见

原因： Metro服务器有多个应用在运行或用户界面代码错误。一次只能有一个应用使用Metro服务器。

解决方案：

检查是否有多个正在运行的应用：

1. 在运行Metro服务器的终端中按Ctrl+C以将其关闭。

2. 停止应用：

   复制代码 已复制到剪贴板。

    vega device terminate-app
   

3. 重启应用：

   复制代码 已复制到剪贴板。

    vega device launch-app
   

检查用户界面代码错误：

1. 监控Metro服务器输出中是否存在由不兼容的React Native程序包引起的错误。

2. 修复代码中的错误。每次更改后，Metro服务器都会自动重建Bundle。

应用在启动时因JavaScript Bundle错误而崩溃

原因： 系统中的某个JavaScript Bundle导致冲突。您的应用不会出现在设备上或vlcm list输出中。日志显示“Requiring unknown module”（需要未知模块）或“Property __d doesn't exist”（属性__d不存在）错误。

解决方案：

1. 捕获设备日志：

   vega device start-log-stream --device <设备名称>
   

2. 使用以下命令之一启动您的应用：

   • 如果使用Vega CLI：

     复制代码 已复制到剪贴板。

     react-native run-app  
     

   • 如果在package.json中使用NPM脚本：：

     复制代码 已复制到剪贴板。

     npm run start:vega
     

3. 检查日志流中是否存在错误模式。

   以下示例显示了与此问题相关的常见错误：

   “Requiring unknown module”错误：

   Uncaught Error: Requiring unknown module "2827612701754778". If you are sure the module exists, try restarting Metro.
   

   “Property '__d' doesn't exist”错误：

   E Volta:[VegaScript-Native] Exception occurred in MessageQueue::runAsync: 
   [Property '__d' doesn't exist
   ReferenceError: Property '__d' doesn't exist at global
   

4. 在运行Metro服务器的终端中按Ctrl+C来停止Metro服务器。

5. 清除Metro缓存并重新启动：

   npx react-native start --reset-cache
   

6. 重建并重新启动应用。

   如果错误仍然存在，请检查是否存在冲突的系统Bundle。有关详细信息，请参阅由于系统Bundle问题，应用崩溃或显示空白屏幕。

由于系统Bundle问题，应用崩溃或显示空白屏幕

原因： 系统Bundle缺失或配置错误。应用还可能具有替代默认Bundle拆分行为的旧标记。缺少系统Bundle通常意味着，设备上的操作系统版本与用于构建应用的SDK版本不匹配。

解决方案：

1. 在应用的根目录（主package.json所在的位置）运行以下命令，以清理缓存并更新依赖项：

   步骤	npm	Yarn	PNPM
   清理缓存	npm cache clean --force	yarn cache clean --all	pnpm cache delete
   重置Metro缓存	npm start -- --reset-cache	yarn start -- --reset-cache	pnpm start -- --reset-cache
   清理构建工件	npm run clean	yarn clean	pnpm clean
   更新依赖项	npm update	yarn upgrade	pnpm update

2. 运行以下命令，验证应用是否使用系统Bundle：

   vega exec vpt dump {path/to/vpkg} assets/raw/keplerscript-app-config.json > keplerscript-app-config.json
   

3. 打开keplerscript-app-config.json文件。

4. 查找"systemBundles: {"部分。

5. 从项目中删除旧的Bundle拆分标记。

   如果之前选择过退出Bundle拆分，则项目可能仍包含阻止系统Bundle正常运行的标记。不再需要这些标记。默认情况下，SDK v0.20及更高版本会启用Bundle拆分。

   • 在package.json中，从"kepler"部分中删除useSystemJsBundles。
   • 在构建脚本中，从构建命令中删除--split-bundle false和--use-system-js-bundles。

6. 如果问题仍然存在，请验证设备上的操作系统版本是否与用于构建应用的SDK版本相匹配。如果不匹配，则更新SDK并重建。有关构建说明，请参阅使用Vega Studio构建应用。

应用在构建后不包含系统Bundle条目

原因： 应用是在调试模式下构建的。调试版本不会创建拆分Bundle，因此系统Bundle条目仅存在于发行版本中。

解决方案： 构建并提交应用的发行版本，而不是调试版本。

相关主题

• 运行您的应用
• 使用Vega Studio构建应用
• 解决Vega Studio构建问题
• 检测应用崩溃的根源
• 管理文件、崩溃报告和日志
• 修复调试问题
• 解决快速刷新问题
• 故障排除

---

Last updated: 2026年3月9日