Debug 是应用开发中关键的一个环节，学习在出现错误、异常等情况下，如何观察现象、定位错误、修复问题，是开发者的基本素质。其中，观察是最为重要的环节，是后续步骤的基石。因此本文的大部分内容将会展示如何在 Zion 中观察得到必要的信息。

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

一、编辑时错误

表现

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

处理办法

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

  1. 类型错误

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

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

  • 必填项缺失

二、部署和发布时错误

表现

  1. 更新预览报错

  2. 后端部署失败

处理办法

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

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

  3. 上报官方解决

后端更新失败 处理办法：直接点击上报，我们官方会进行处理。

三、线上UI显示异常

表现

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

处理办法

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

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

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

b. 比如一个下方一个视图组件里放了一个文本组件，文本组件里文字非常多，超出了视图组件
这个时候想要不超出视图组件，我们可以选中视图组件，把设计-溢出配置从可见改成隐藏，或者你想滚动视图来显示也可以改成溢出-滚动

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

四、请求异常

表现

  1. 报错：行为流调用失败、api执行失败、执行一些内置行为时显示错误信息等

  2. 异常：运行结果不符合业务期待，不符合配置的逻辑

处理办法

根据常见错误处理办法解决问题

查看页面顶部报错信息，对照以下表格判断常见错误类型和处理方法

报错信息 名词解释 导致原因 一般解决方法
Permission check failed 权限检查失败 当前用户没有执行这个行为的权限 去权限配置处检查相应行为的权限
duplicate key value violates unique constraint 数据模型有约束的字段插入了重复的值 检查插入了哪个重复的值看是否符合自身业务逻辑
delete or update must has filter 删除或更新必须添加过滤条件 没有添加过滤条件 检查过滤条件为啥没拿到值
TABLE_ACCESS 访问表 当前用户对某张表没有访问权限 去权限配置处检查相应行为的权限
Action flow not found 找不到行为流 行为流创建建后没有进行后端部署 部署后再执行
ANOTHER_APP_IS_DEPLOYING（项目部署中，请稍候） 项目部署中，请稍候 项目后端正在部署或者某个客户端正在部署过程中又发了一次请求部署的接口 等待部署完成后再尝试
WECHAT_APP_ID_AND_SECRET_REQUIRED（部署失败，请绑定微信后再试） 部署失败，请绑定微信后再试 微信部署，但用户没有提供微信的appId和secret 解绑后重新绑定小程序
CANNOT_DEPLOY_AN_OLDER_SCHEMA（部署失败，请重试） 部署失败，请重试 项目没有拿最新的schema部署（web的publish除外） 尝试刷新页面后重试
PROJECT_ENV_CONFIG_SYNC_ERROR（数据同步失败） 数据同步失败 部署服务端的时候数据同步失败（比如data model， action flow等等） 尝试刷新页面后重试
TARGET_PLATFORM_IS_DEPLOYING（项目部署中，请稍后） 项目部署中，请稍后 单项目的部署过程中发现同一个build_target正在部署 等待部署完成后再尝试
NO_PROJECT_WECHAT_APP_CONFIG（部署失败，缺少必要配置项） 部署失败，缺少必要配置项 部署微信小程序时缺少配置项 解绑后重新绑定小程序
SUPPORT_SERVICE_IS_DEPLOYING（后端部署中，请稍候） 后端部署中，请稍候 后端部署过程中又一次部署 等待部署完成后再尝试
TABLE_NAME_TOO_LONG（表名太长，请修改） 表名太长 表名太长，请修改（超过62个字符） 缩短表名
TABLE_NAME_ALREADY_EXIST（表名已存在，请修改） 表名已存在 表名已存在，请修改 更改表名

通过“开发调试模式”和Zion日志解决

  1. 打开开发模式和zion日志

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

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

    3. 日志：在编辑器内点击右上角“日志”功能

    小程序

    网页

  2. 查看请求的具体内容进行分析

一个请求通常由多部分构成请求构成，我们通常只需要关注请求体（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"里的错误信息。

  • 猜测原因、尝试修复

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

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

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

    4. 还可以让 AI 帮助你分析报错/异常信息。可参考下面的 Prompt（使用时将第5步的信息替换成你自己的）：

  你是一位经验丰富的开发专家，你的任务是分析给定的信息，找出其中可能存在的错误，并向用户提供清晰、简洁的错误描述以及相应的解决方案。

请按照以下步骤进行操作：

# 1. 分析信息
* 检查请求的语法是否正确，包括关键字、操作类型、字段选择、参数传递等。
* 理解请求的目标，即用户希望从服务器获取哪些数据或执行哪些操作。

# 2. 识别错误类型和原因
* 参考以下常见错误处理办法，先检查是否在其中出现；如果没有，你再自己分析错误原因和解决方式
| 报错信息                                                    | 名词解释          | 导致原因                                        | 一般解决方法                 |
| ------------------------------------------------------- | ------------- | ------------------------------------------- | ---------------------- |
| Permission check failed                                 | 权限检查失败        | 当前用户没有执行这个行为的权限                             | 去权限配置处检查相应行为的权限        |
| duplicate key value violates unique constraint          |               | 数据模型有约束的字段插入了重复的值                           | 检查插入了哪个重复的值看是否符合自身业务逻辑 |
| delete or update must has filter                        | 删除或更新必须添加过滤条件 | 没有添加过滤条件                                    | 检查过滤条件为啥没拿到值           |
| TABLE\_ACCESS                                           | 访问表           | 当前用户对某张表没有访问权限                              | 去权限配置处检查相应行为的权限        |
| Action flow not found                                   | 找不到行为流        | 行为流创建建后没有进行后端部署                             | 部署后再执行                 |
| ANOTHER\_APP\_IS\_DEPLOYING（项目部署中，请稍候）                  | 项目部署中，请稍候     | 项目后端正在部署或者某个客户端正在部署过程中又发了一次请求部署的接口          | 等待部署完成后再尝试             |
| *WECHAT\_APP\_ID\_AND\_SECRET\_REQUIRED（部署失败，请绑定微信后再试）* | 部署失败，请绑定微信后再试 | 微信部署，但用户没有提供微信的appId和secret                 | 解绑后重新绑定小程序             |
| *CANNOT\_DEPLOY\_AN\_OLDER\_SCHEMA（部署失败，请重试）*           | 部署失败，请重试      | 项目没有拿最新的schema部署（web的publish除外）             | 尝试刷新页面后重试              |
| *PROJECT\_ENV\_CONFIG\_SYNC\_ERROR（数据同步失败）*             | 数据同步失败        | 部署服务端的时候数据同步失败（比如data model， action flow等等） | 尝试刷新页面后重试              |
| *TARGET\_PLATFORM\_IS\_DEPLOYING（项目部署中，请稍后）*            | 项目部署中，请稍后     | 单项目的部署过程中发现同一个build\_target正在部署             | 等待部署完成后再尝试             |
| *NO\_PROJECT\_WECHAT\_APP\_CONFIG（部署失败，缺少必要配置项）*        | 部署失败，缺少必要配置项  | 部署微信小程序时缺少配置项                               | 解绑后重新绑定小程序             |
| *SUPPORT\_SERVICE\_IS\_DEPLOYING（后端部署中，请稍候）*            | 后端部署中，请稍候     | 后端部署过程中又一次部署                                | 等待部署完成后再尝试             |
| TABLE\_NAME\_TOO\_LONG（表名太长，请修改）                        | 表名太长          | 表名太长，请修改（超过62个字符）                           | 缩短表名                   |
| *TABLE\_NAME\_ALREADY\_EXIST（表名已存在，请修改）*                | 表名已存在         | 表名已存在，请修改                                   | 更改表名                   |


# 3. 提供错误描述和解决方案

* 对于每一个识别出的错误，用清晰简洁的语言描述错误信息，指出错误发生的具体位置（例如：哪个字段、哪个参数）。
* 针对每个错误，提供至少一种明确可行的解决方案。解决方案应该具体、可操作，并指导用户如何修改他们的请求。
* 如果可能，提供一些额外的建议或最佳实践，以帮助用户避免类似错误的发生。

# 4. 输出格式要求
* 首先，明确指出是否存在错误。
* 如果存在错误，请使用列表或编号的方式逐个列出错误及其解决方案。
* 对于每个错误，按照以下格式输出：
    * **错误描述：** [清晰描述错误信息]
    * **解决方案：** [提供具体的解决方案]
* 如果不存在明显的错误，但响应数据可能存在问题，请指出可能的问题和排查方向。

# 5. 具体的信息
{
    "data": {
        "update_blog_by_pk": null
    },
    "errors": [
        {
            "errorCode": 400,
            "extensions": {
                "classification": "DUPLICATE_KEY"
            },
            "locations": [
                {
                    "column": 3,
                    "line": 2
                }
            ],
            "message": "StatementCallback; ERROR: duplicate key value violates unique constraint \"unique_blog_m8fifp2i\"\n  Detail: Key (title)=(1) already exists.",
            "operation": "update_blog_by_pk",
            "path": [
                "update_blog_by_pk"
            ]
        }
    ]
}

参考案例

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

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

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

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

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

五、debug基本原则

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

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

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

2. 分模块检查配置

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

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

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

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

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

3. 验证

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

六、技术支持和参考资料

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

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

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

举例：

  1. 你期待什么样的效果

  2. 已做过的尝试

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

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

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

“为什么预览报错了”

“怎么做一个商城？”

  • 购买官方技术支持：在个人中心购买专属技术支持
Copyright © FunctorZ 2024 all right reserved修订时间： 2025-03-19 11:09:58

results matching ""

    No results matching ""