小程序及网页开发中的异常错误诊断与调试方法

Debug 是应用开发中关键的一个环节，学习在出现错误、异常等情况下，如何观察现象、定位错误、修复问题，是开发者的基本素质。

其中，观察是最为重要的环节，是后续步骤的基石。因此本文的大部分内容将会展示如何在 Zion 中观察得到必要的信息。

在 Zion 中有三类错误内容，编辑时错误、部署和发布时错误、应用运行时错误。本文将按照不同分类给大家介绍每一种错误应该如何去解决（debug）。

一 · 编辑时错误

表现

编辑器右上角错误图标有数字显示

处理办法

点击去修复会跳转到错误位置，根据报错提示去修改，以下是两个例子

1. 类型错误

组件、行为或数据中绑定数据的类型错误.需为(Null | Nothing|Int)，实际为：String

分析和处理办法：在添加表数据行为原价字段上填入“1元“后可以看到编辑器提示有错误，分析错误可知是一个类型错误，原价字段是个Int类型的数值字段，不能填入文本类型值，所以“元”字应该去掉。

2. 必填项缺失

二 · 部署和发布时错误

表现

1. 更新预览报错

2. 后端部署失败

处理办法

1. 查看错误信息（如有）

2. 根据错误信息处理错误，看不懂可以问ai

3. 上报官方解决

4. 后端更新失败 

处理办法：直接点击上报，我们官方会进行处理。

三 · 线上UI显示异常

表现

如编辑器上高度对齐的两个组件在预览后没有对齐或者编辑器上看起来宽度正常的组件在手机上查看是超出屏幕宽度。

处理办法

1. 检查组件的UI设计配置

    ✥ 比如下方两个在编辑器上看起来左对齐的两个组件，一个使用相对布局，一个使用绝对布局；

当它们在不同宽度的容器上显示会不对齐，原因是编辑器默认的宽度是375，所以在宽度375的机型上显示正常，在宽度430的机型上，绝对布局是相对于父组件的坐标显示，所以会往左偏。

比如一个下方一个视图组件里放了一个文本组件，文本组件里文字非常多，超出了视图组件。

这个时候想要不超出视图组件，我们可以选中视图组件，把设计-溢出配置从可见改成隐藏，或者你想滚动视图来显示也可以改成溢出-滚动。

比如编辑器上两个组件看起来平齐，手机上查看没有对齐，检查配置后如果没有发现错误，可能是我们的bug，可在微信群里反馈给官方。

四 · 请求异常

1. 根据错误信息快速处理

请求错误时，通常会在前端页面或请求里抛出错误消息：

    ✥ 可前根据以下的错误对照表，检查是否有对应的错误和处理方式

    ✥ 也可以尝试让 AI 帮助你分析错误信息，参考下面的提示词（将第五步的错误信息替换成你自己的）

你是一位精通 PostgreSQL 数据库和 GraphQL API 的开发专家。你的任务是：
1.  **分析请求信息：**    
* 检查 GraphQL 请求的语法是否正确，包括查询、变更、订阅等操作类型，以及字段选择、参数传递等。    
* 理解请求的目标，即用户希望从服务器获取哪些数据或执行哪些操作。    
* 检查数据库返回的错误信息。
2.  **识别错误类型和原因：**    
* 根据错误信息，确定错误的具体类型（例如：语法错误、类型错误、数据库约束冲突等）。    
* 分析错误的原因，包括但不限于：        
* GraphQL 请求中的语法错误或类型错误。        
* 数据库中的数据约束冲突（例如：唯一性约束、外键约束等）。        * 数据库连接问题或权限问题。
3.  **提供详细的错误描述和解决方案：**    
* 对于每个识别出的错误，用清晰简洁的语言描述错误信息，并指出错误发生的具体位置（例如：哪个字段、哪个参数、哪个表）。    * 针对每个错误，提供至少一种明确可行的解决方案。解决方案应该具体、可操作，并指导用户如何修改他们的请求或数据库。    
* 如果可能，提供一些额外的建议或最佳实践，以帮助用户避免类似错误的发生。    
* 不要给出 GraphQL API 层面 的建议。    
* 如果你无法分析出错误原因，直接告诉用户你不知道。
4.  **输出格式要求：**    
* 首先，明确指出是否存在错误。    
* 如果存在错误，请使用列表或编号的方式逐个列出错误及其解决方案。    
* 对于每个错误，按照以下格式输出：        
* **错误描述：** \[清晰描述错误信息]        
* **解决方案：** \[提供具体的解决方案]    
* 如果不存在明显的错误，但响应数据可能存在问题，请指出可能的问题和排查方向。
5.  **具体的信息：**    
* StatementCallback; ERROR: duplicate key value violates unique constraint \"unique\_blog\_m8fifp2i\"\n Detail: Key (title)=(1) already exists.

如果上面的措施都无法解决问题，再进行后续步骤。

2. 找到错误或异常的请求

可在小程序和浏览器的控制台，或在 Zion 的日志系统中找到：   

✥ 小程序：点击右上角菜单，选择开发调试，点击vConsole，找到相应的 request 和 result

    ✥ 网页：按F12键，或者右键页面，选择“检查”，打开调试模式，点击network，在下方找到graphql-v2的请求

      ✥ 日志：在编辑器内点击右上角“日志”功能，更多日志的内容请前往Zion帮助中心搜索“日志服务”查看

3. 分析请求的内容

一个请求通常由多部分构成（[请求的主要构成](https://blog.csdn.net/weixin_43195445/article/details/84639239)），我们通常只需要关注请求体（Request body）和响应体（Response body）。

✥ 请求体（Request body）包含了发送的请求的关键信息，可以在小程序的"request"中和浏览器的"Payload"中查看请求体内容。

在 Debug 时，可以通过观察请求体，检查其和编辑器中的配置是否都能够一一对应。用上面第二张图中的请求体做例子：

{    "query": "query blogArticleList_82df5ec2($where: blog_article_bool_exp!,     $orderBy: [blog_article_order_by!]!) {blog_article ( where: $where order_by: $orderBy  limit: 2) { id \n title}\n\n}",    "variables": {        "where": {            "title": {                "_like": "%AI%"            }        },        "orderBy": [            {                "created_at": "asc_nulls_last"            }        ]    }}

query的部分是查询的语句，决定了请求数据的结构，可以从中看出很多关键信息。在本例中，可以从中看出查询的是 blog_article 表、限额查询2条（limit: 2）等信息。

variables的部分是本次查询的参数，对应了在编辑器中配置的筛选条件、排序、去重等。在本例中，从"where"部分可以看出筛选条件为：title 中包含 AI；从"orderBy"部分可以看出，以"created\_at"进行升序排序。

✥ 响应体（Response body）包含了这次请求的返回结果。可以在小程序的"result"中和浏览器的"Response"中查看响应结果，如果报错，可以在"Response"找到"errors"

例如权限的错误信息：

{  "data": null,  "errors": [      {          "errorCode": 403,          "extensions": {              "classification": "TABLE_ACCESS"          },          "locations": [              {                  "column": 3,                  "line": 2              }          ],          "message": "User 1 has no permission for SELECT on order",          "operation": "order",          "path": [              "order"          ]      }  ]}

4. 猜测原因、尝试修复

✥ 通过观察请求体，检查查询语句和参数是否和编辑器中的配置一一对应

✥ 通过观察响应体，检查是否有错误，以及结果是否符合预期

✥ 获取足够信息后，可以猜测异常的大体原因并尝试修复

✥ 如果无法分析出错误原因，可以将上面获得的信息发给 AI，参考使用第一步中的提示词

5. 参考案例

1. 比如支付、退款执行错误，用户执行退款行为失败，在手机上打开调试模式或者在日志里找到错误信息，可以看到是权限配置错误，即可去项目权限配置处检查已登录角色的退款行为权限是否配置

2. 比如小程序api执行错误，可先点击'Clear'清除日志，再点击操作按钮，找到最近的请求，分析下图错误可知是参数_9对应的字段需要非空的文本值，但此处只传了一个null值

3. 比如某行为流执行失败或执行后不符合期待，在日志里查询相关报错，以下是某项目执行失败，分析报错可知是字段foodwcost未定义，应该写错了，正确的是foodcost

4. 比如更改表数据错误，分析下面错误可知是在插入表数据时插入了一个重复的值，跟数据库已存在的值产生了冲突

5. 比如配置一个条件式容器，只有数据源里name字段值等于“真”才显示有“真”的按钮，否则显示有“假”的按钮，但是看到预览里条件式容器显示假，按f12打开浏览器开发工具找到对应请求可知，查询到的name值不是“真”而是“直”

五 · debug基本原则

1. 明确问题现象与复现路径

✥ 现象描述：记录具体的错误表现（如条件式容器显示错误、数据未修改或插入、有报错提示等），包括触发条件和异常提示信息。

✥ 复现步骤：尝试在相同操作路径下复现问题，确认是否为偶发或持续性问题。

2. 分模块检查配置

✥ 模块配置验证：按功能模块逐一检查配置逻辑。例如：

    ✧ 表单模块：字段类型、必填规则、数据校验条件是否合理

    ✧ 工作流模块：步骤顺序、条件分支、权限分配是否正确

    ✧ 数据关系：表间关联字段是否匹配

✥ 依赖项排查：若使用了第三方服务，检查外部集成服务（如API接口、第三方插件）的连通性及参数配置

3. 验证

✥ 增量修复验证：每次调整后仅修改单一变量，逐步验证问题是否解决，避免多配置变更导致干扰

六 · 技术支持和参考资料

1. 平台帮助文档：查阅官方文档中的“常见问题”章节，获取针对性的解决方案 。

2. 社区支持：在社区community.functorz.com 中发帖，或者在用户群内提问，需附上项目ID、复现步骤、截图及日志

【正确提问姿势】求助请详细描述及附带截图以提高问题的回复及时性

举例：

1. 你期待什么样的效果

2. 已做过的尝试

3. 错误发生在哪个页面哪个组件

提供错误信息或截图 （截图比拍屏更好哦）

【错误提问示范】一句话式的提问

“为什么预览报错了”

“怎么做一个商城？”

3. 购买官方技术支持：在个人中心购买专属技术支持