LIFF SDK 错误

在开发基于 LINE Front-end Framework（LIFF）的应用时，开发者可能会遇到各种 SDK 抛出的异常或错误。这些错误通常以 LiffError 对象的形式返回，包含多个属性，其中最关键的两个属性是 code（错误代码）和 message（错误信息）。为了确保 LIFF 应用具备更好的稳定性和兼容性，开发者应始终依赖这两个属性来识别和处理错误，而不仅仅是依赖错误信息中的文字描述。

LiffError 对象结构

当 LIFF SDK 在执行某个操作时发生异常，例如获取用户资料、启动应用、调用权限 API 等，会抛出一个 LiffError 实例。这个对象的结构如下：

{
  "code": "ERROR_CODE_SAMPLE",
  "message": "Human-readable error message describing the error"
}

• code：错误代码，通常是一个有语义的标识符（例如：INVALID_PARAMETER, PERMISSION_DENIED, NETWORK_ERROR 等），不会轻易变动。
• message：详细的错误描述，通常是可读性较强的字符串，用于辅助开发者调试，但可能因版本、语言或其他变化而随时更改。

常见开发误区：依赖错误信息文字匹配

许多开发者在初次使用 LIFF SDK 时，倾向于通过比较 message 属性的具体内容来判断错误类型。如下代码所示：

if (error.message === 'Permission denied') {
  // 执行某些处理逻辑
}

虽然这种方法在某些情况下可以临时生效，但并不可靠。因为错误信息可能会随着 SDK 更新而变化，甚至可能因语言设置不同而返回不同的文本。这就意味着一旦 message 字符串发生细微变化，原本可用的错误处理逻辑将失效，可能导致功能异常或用户体验下降。

LIFF SDK 错误 ：使用错误代码 + 错误信息

为了确保应用具备良好的前向兼容性与鲁棒性，建议始终使用错误代码来判断错误类型，并仅将错误信息用于日志记录或用户提示。

示例：

try {
  await liff.permission.requestAll();
} catch (error) {
  if (error.code === 'PERMISSION_DENIED') {
    console.error('权限被拒绝:', error.message);
    // 提示用户开启权限或引导至设置界面
  } else if (error.code === 'NETWORK_ERROR') {
    console.warn('网络问题:', error.message);
    // 尝试重连或提示网络异常
  } else {
    console.log('其他错误:', error.code, error.message);
    // 默认错误处理逻辑
  }
}

在上述代码中，开发者基于 code 来分类错误逻辑，同时保留 message 作为日志输出或 UI 反馈内容，这样即使错误信息发生变化，核心判断逻辑依然可以稳定运行。

错误代码的稳定性

与错误信息不同，错误代码是 SDK 设计中为支持程序逻辑判断而预留的字段。根据 LINE 官方文档的说明，错误代码的命名与分类相对固定，不会在版本升级中随意更改。这意味着基于错误代码的逻辑判断具备长期稳定性，更适合作为生产级代码的核心判断依据。

错误处理策略建议

在处理 LIFF SDK 错误时，建议遵循以下几点策略：

1. 错误归类管理：根据错误代码构建统一的错误分类管理模块，例如网络错误类、权限错误类、参数错误类等，便于后续维护。
2. 用户友好提示：根据错误类型，设计清晰明确的用户提示，引导用户解决问题而非直接报错退出。
3. 日志记录与监控：将 code 与 message 同步记录到日志系统中，辅助定位与分析问题。
4. 版本兼容性检测：定期关注 LINE软件官方 SDK 更新日志，确认错误代码是否发生变化，以便及时修复潜在问题。
5. 多语言支持考虑：避免将 message 直接暴露给用户作为提示内容，可根据错误代码定义多语言翻译表，提升用户体验一致性。

示例错误代码列表（假设）

错误代码	含义说明
INVALID_PARAMETER	请求中包含无效参数
PERMISSION_DENIED	用户拒绝授权或权限请求失败
NETWORK_ERROR	当前网络不可用或请求超时
UNAUTHORIZED	用户未登录或凭证失效
UNKNOWN_ERROR	未知错误，需联系技术支持

请注意：实际错误代码可能会有所不同，开发时应以最新官方文档为准。

规范化的错误处理策略

在 LIFF 应用开发过程中，正确地识别和处理 SDK 错误是确保应用稳定运行的重要保障。依赖错误信息的精确字符串匹配虽然简单快捷，但存在严重的稳定性问题。推荐始终使用 LiffError 中的 code 属性作为主要判断依据，同时将 message 用于辅助调试与用户提示。通过规范化的错误处理策略，开发者可以显著提升 LIFF 应用的鲁棒性、可维护性与用户体验，避免因 SDK 升级带来的意外故障。