writing-error-messages

编写错误消息

快速入门

开始编写前，先确定：

1. 受众： 终端用户、管理员、开发者、支持人员或运维人员。
2. 失败情况： 哪项操作失败了，还有哪些操作成功完成。
3. 原因： 已知、未知、用户可修正、服务端、第三方或涉及安全。
4. 恢复方式： 读者现在可以做什么、系统接下来会做什么，以及可以从哪里获得帮助。

然后按以下结构编写：

[What happened]
[Reassurance if useful]. [Why it happened, if known and safe]. [Specific next action]. [Backup path if it keeps happening].

示例：

Unable to connect your account
Your changes were saved, but we couldn't connect the account because of an issue on our end. Try connecting again. If this keeps happening, contact support.

核心规则

规则	应该做	避免
说明发生了什么	“我们无法保存你的文件。”	“出了点问题。”
说明哪些内容未受影响	“你的草稿已保存。”	让用户担心数据是否丢失
给出下一步操作	“检查卡号，然后重试。”	仅提供“确定”／“关闭”作为处理方式
使用通俗语言	“我们无法连接到 Dropbox。”	“获取失败”／“凭据被拒绝”
不要指责用户	“必须填写商店名称。”	“你忘了填写商店名称。”
语气与严重程度相符	冷静、直接、尊重	“哎呀！”／开玩笑／过分可爱的语气
在安全的前提下提供具体信息	“请输入过去的日期。”	“输入无效。”
安全要求时保持笼统	“电子邮件地址或密码无效。”	“该电子邮件地址已注册，但密码错误。”

消息结构

只使用当前情况所需的部分。

部分	用途	模式
标题	概述失败的操作	“无法保存更改”
正文	说明后果和原因	“你的更改仍处于打开状态，但由于连接中断，我们无法保存。”
主要操作	告诉读者该怎么做	“重试”、“更新详细信息”、“选择其他文件”
备用途径	提供其他解决方式	“如果问题仍然存在，请联系支持人员。”
诊断信息	帮助技术人员或支持人员排查问题	错误代码、请求 ID、预期值／实际值、日志位置

尽可能将 UI 正文控制在 1–2 句话。较长的诊断信息应放在可展开文本、日志或支持信息中。

参考资料

• 审核大量消息、权衡措辞或核对有来源支持的理由时，打开 references/source-backed-patterns.md。
• 重写多条消息或检查此技能是否生成了合适的结构时，打开 references/rewrite-examples.md。

验证和表单错误

对于字段级错误：

• 将消息放在字段旁边；对于较长的表单，应在顶部汇总错误。
• 使用与字段标签或问题一致的措辞，让读者知道消息对应哪个控件。
• 说明如何修正，而不只是指出错误。
• 保留用户输入，方便他们进行修正。
• 在用户有充分时间完成输入之前，不要进行验证。

推荐模式：

Enter an email address
Enter a date in the past
Password must be at least 12 characters
Choose a file smaller than 10 MB

避免：

This field is required
Invalid input
You entered an illegal value
Validation failed

位置、无障碍和空状态

• 将错误放在读者正在查看的位置：字段、控件、提示消息的来源或失败的项目附近。
• 不要只依赖颜色。在 UI 代码中，应加入可见文本、图标或标签，以及机器可读的语义信息。
• 对于表单页面，应根据产品的无障碍模式，将焦点移至错误摘要或第一个错误。
• 尽可能保留用户的操作内容。
• 不要将空结果当作错误。如果没有任何操作失败，应显示空状态：“未找到发票”，并提供下一步有用操作。

安全与隐私检查

具体说明不总是更好。如果详细信息可能泄露账户是否存在、权限、私密数据、系统内部信息、欺诈信号或安全策略，请使用笼统的消息。

登录和账户恢复时使用笼统的文案：

Invalid email or password
If an account exists for that email address, we'll send password reset instructions.

不要泄露：

That email exists, but the password is wrong
This account is locked
No account found for this email

如果用户需要帮助，请提供安全的途径：联系支持人员、恢复说明、请求 ID，或不会影响审计安全的解释。

面向开发者和 CLI 的错误

当读者可以根据技术细节采取行动时，请以结构化方式提供这些信息：

Could not read config file
Expected TOML at ./app.config.toml, but found invalid syntax on line 12: missing closing quote.
Fix the syntax and run `app deploy` again.

有用的细节：

• 哪个命令、文件、字段或资源发生了故障。
• 预期是什么，实际收到的是什么。
• 最小修复方法或下一条诊断命令。
• 如果需要支持或调试，提供请求 ID、错误代码或日志路径。

仍应避免提供堆栈跟踪、原始异常名称和内部服务名称，除非读者能够利用这些信息。

用户要求提供通用错误时

不要在未确认产品是否能提供更好信息的情况下，接受“只写一条通用错误”的要求。请询问：

• 用户尝试完成什么操作？
• 代码或服务中的什么因素触发了此错误？
• 原因是已知、未知、间歇性出现，还是涉及安全敏感问题？
• 是否有任何内容已保存、发送、扣费、删除，或保持不变？
• 用户能否自行修复、重试、等待、换一种方式操作，或联系支持人员？
• 此问题发生得有多频繁，是否会阻断主要流程？

如果确实无法确定原因，请使用通用但可采取行动的备用提示：

Something went wrong
Refresh the page and try again. If this keeps happening, contact support with request ID {request_id}.

最终检查

发布前，请确认消息回答了读者的疑问：

1. 发生了什么？
2. 我是否丢失了什么内容，或创建了重复内容？
3. 如果可以安全说明，为什么会发生这种情况？
4. 我接下来可以做什么？
5. 如果我什么都不做，会发生什么？
6. 如果修复方法不起作用，我可以从哪里获得帮助？