如何让 Codex 帮你优化空状态和错误提示

很多网站和 SaaS 产品看起来已经做完了页面，但一旦遇到没有数据、搜索无结果、接口加载失败、表单提交失败、权限不足，就会暴露出明显的“不像成熟产品”的问题。最常见的表现是：页面空着、只写“暂无数据”、错误直接显示后端返回、提示离出错位置很远、用户不知道下一步该点哪里。

空状态和错误提示不是边角料。它们决定用户在产品“不顺利”的时候，是否还能理解当前发生了什么，并继续完成任务。对前端项目来说，这类问题也很适合交给 Codex 处理：因为它不仅能改文案，还能顺着代码找到状态判断、组件复用、接口异常处理、表单校验和页面布局问题。

更准确地说，你不应该只让 Codex “帮我优化一下错误文案”。这条指令太泛，最后很容易得到几句更好听但没有落地价值的文案。更好的方式是让 Codex 先做状态盘点，再按场景分类，最后用小步改动完成组件和文案优化。

一、为什么空状态和错误提示值得单独优化

成熟产品和 Demo 页面最大的差别，往往不是首页，而是异常场景。用户第一次进入某个功能，还没有创建任何内容，这是空状态；搜索不到结果，这是无结果状态；接口请求失败，这是错误状态；表单字段不合法，这是校验错误；没有权限访问，这是权限状态。它们看起来都像“没有内容”，但真实含义完全不同。

如果所有地方都统一写成“暂无数据”，用户会分不清是自己还没有操作、筛选条件太窄、网络失败、权限不够，还是系统真的坏了。好的状态设计至少要回答三个问题：

• 现在为什么没有内容？

• 这是不是用户的错，还是系统/网络/权限导致？

• 用户下一步应该做什么？

这也是 Codex 适合介入的原因。空状态和错误提示不是单点设计问题，而是散落在页面、组件、接口封装、表单校验和路由权限里的系统问题。人工逐页查容易漏，Codex 可以先读项目结构，再把所有状态入口列出来。

二、Codex 能帮你检查哪些问题

让 Codex 检查空状态和错误提示时，不要只盯文案。你真正要它检查的是一整套体验链路。

三、先让 Codex 做“状态盘点”，不要直接让它改

直接让 Codex 修改，最大的问题是容易改偏：它可能只在几个明显页面里替换文案，却没有找到真正的状态来源。更稳的流程是先让它输出盘点报告，不要写代码。

• 扫描路由、页面和核心组件。

• 找出所有 loading、empty、error、not found、unauthorized、validation error 的判断。

• 按页面列出当前文案、组件、按钮和触发条件。

• 标出缺失状态和重复状态。

• 给出优先级：先处理影响主流程的页面，再处理低频页面。

这一步的产物应该是一份清单，而不是代码 diff。你可以先看清楚项目里到底有多少种“空”和“错”，再决定是否让 Codex 进入修改阶段。

四、空状态需要分 5 类处理

空状态不等于“没有数据”。不同空状态背后的用户心理不同，提示方式也不同。让 Codex 优化时，可以要求它按下面 5 类归档。

这里最容易犯的错是把“接口失败”也写成空状态。例如订单列表加载失败时，页面显示“暂无订单”，用户会误以为自己没有订单；真实情况可能是网络失败或后端报错。Codex 要做的第一件事，就是帮你把 empty 和 error 分开。

五、错误提示需要分层：页面级、区域级、字段级

错误提示也不能只写一种。一个成熟产品至少要区分三层错误：

• 页面级错误：整个页面无法加载，例如 404、500、接口不可用。

• 区域级错误：页面局部模块失败，例如图表加载失败、列表请求失败。

• 字段级错误：表单输入不合法，例如邮箱格式错误、密码不满足规则。

让 Codex 优化时，要明确要求它不要把所有错误都做成 Toast。Toast 适合轻量反馈，但不适合作为核心表单错误或页面加载失败的唯一提示。字段级错误应该贴近字段，区域级错误应该留在模块内部，页面级错误才适合用完整错误页。

六、让 Codex 优化文案时，用“原因 + 影响 + 下一步”

错误提示不是为了显得客气，而是为了降低用户恢复成本。比较稳的文案结构是：

• 原因：发生了什么。

• 影响：用户现在不能做什么。

• 下一步：用户可以怎么恢复。

例如，不要写“请求失败”。可以改成“项目列表暂时加载失败，请检查网络后重试”。如果能提供按钮，就给“重新加载”；如果是筛选无结果，就给“清空筛选”；如果是权限不足，就给“联系管理员”。

七、完整 Codex 提示词：先审查，再给方案

下面这条适合第一次让 Codex 进入项目做空状态和错误提示检查。重点是：先不要改代码，先输出清单和方案。

请你作为资深前端工程师 + UI/UX 体验审查员，帮我检查当前项目里的空状态和错误提示。先不要修改代码，先输出一份审查报告。

目标：

系统性找出项目中所有容易让用户困惑的空状态、无结果状态、加载失败、接口错误、权限错误和表单错误提示，并给出优化建议。

请按以下步骤执行：

1. 先阅读项目结构，识别主要路由、页面、列表、表格、搜索、筛选、表单、详情页和权限相关组件。

2. 搜索代码中的关键词和状态判断，包括但不限于：empty、no data、not found、error、failed、loading、unauthorized、forbidden、暂无、失败、错误、无权限、没有数据。

3. 按页面列出当前状态处理方式：触发条件、当前文案、当前组件、是否有操作按钮、是否能恢复。

4. 将状态分为：首次使用空状态、搜索无结果、筛选无结果、数据加载失败、权限不足、表单字段错误、页面不存在、服务器错误。

5. 判断每个状态是否存在以下问题：文案过泛、没有说明原因、没有下一步、错误位置不对、组件不统一、移动端可能溢出、只靠颜色表达错误。

6. 输出一份优先级清单，优先处理影响主流程和高频页面的问题。

输出格式：

• 总体结论

• 状态问题清单表格

• 高优先级页面

• 建议新增或统一的组件

• 每类状态的推荐文案规则

• 修改风险点

• 下一步可执行的修改计划

限制：

• 本轮不要直接改代码。

• 不要改变业务逻辑。

• 不要凭空新增复杂功能。

• 如果有不确定的状态来源，请标注“不确定”，并说明需要我确认什么。

八、第二条 Codex 提示词：开始修改组件和文案

当 Codex 输出审查报告后，再让它进入修改阶段。这里要给边界：只做小步、可 review 的改动，不要顺手重构整个项目。

根据你刚才输出的空状态和错误提示审查报告，请开始做第一轮改造。请优先处理高频页面和主流程页面，保持小步、可 review 的改动。

改造目标：

1. 统一空状态和错误状态的展示组件。

2. 将“暂无数据 / 请求失败 / 系统错误 / 无权限”等泛化文案，改成更具体、可理解、有下一步动作的文案。

3. 区分 empty state、no result、error state、permission state、validation error，不要混用。

4. 保持现有视觉风格，不重新设计页面，不改变业务逻辑。

请按以下要求修改：

• 如项目已有 EmptyState / ErrorState / Alert / Toast / FormError 组件，优先复用和增强，不要重复造轮子。

• 如没有统一组件，请新增轻量组件，并保证 props 简单，例如 title、description、primaryAction、secondaryAction、variant。

• 表单字段错误要靠近字段显示，不要只用 Toast。

• 列表或表格的搜索无结果，要提供“清空筛选”或“重置搜索”的动作。

• 接口加载失败要提供“重新加载”动作，不要显示成普通空状态。

• 权限不足要说明原因和下一步，例如联系管理员或返回上一页。

• 注意移动端换行、按钮排列、最小高度和空状态居中方式。

完成后请输出：

1. 修改了哪些文件。

2. 每个页面状态如何变化。

3. 新增或调整了哪些组件。

4. 需要我人工确认的文案或业务规则。

5. 如何运行项目并验证这些状态。

验收标准：

• 不再出现明显无意义的“暂无数据”“请求失败”“系统错误”。

• 每个主要空状态都有原因说明和下一步动作。

• 错误状态和空状态不混用。

• 主流程页面在移动端不溢出。

• lint / typecheck / build 能通过，如项目有对应脚本请运行。

九、第三条 Codex 提示词：专门优化 UX 文案

如果项目已经有组件，只是文案很差，可以让 Codex 专门做 UX writing 审查。

请你只优化当前项目里的空状态和错误提示文案，不要改业务逻辑和页面结构。

文案目标：

• 具体，不写泛泛的“暂无数据”“请求失败”。

• 解释原因，让用户知道为什么看到这个状态。

• 给出下一步，让用户知道可以做什么。

• 语气自然、专业、克制，不卖萌，不夸张。

• 中文文案优先，如果项目支持多语言，请同时检查 i18n 文案文件。

请输出并修改：

1. 找到所有空状态和错误提示文案。

2. 将它们按场景分类。

3. 对每一句文案给出替换版本。

4. 修改代码或 i18n 文件。

5. 输出修改前后对照表。

限制：

• 不要增加新功能。

• 不要改变接口字段和业务判断。

• 不要把后端错误原文直接展示给用户，除非它本身已经是面向用户的文案。

• 保留必要的调试信息在日志中，但不要暴露给普通用户。

十、可以沉淀成项目规范的组件规则

如果你经常让 Codex 处理 UI 体验，可以把空状态和错误提示规则写进 AGENTS.md 或项目规范文档。这样之后每次新增页面，Codex 都会默认遵守。

这类规则越具体，Codex 越不容易写出“看似合理但实际不可用”的状态。例如你可以明确：搜索无结果必须有“清空筛选”，接口失败必须有“重试”，权限不足必须有“联系管理员”或“返回”。

十一、建议写进 AGENTS.md 的规则

可以把下面这段直接放进项目的 AGENTS.md，作为长期规范。

Empty states and error messages

When adding or modifying pages, always handle loading, empty, no-results, error, permission, and validation states explicitly.

Rules:

• Do not use generic copy such as "No data", "Error", "Failed", "暂无数据", "请求失败", or "系统错误" unless there is no better context available.

• Empty states must explain why the area is empty and what the user can do next.

• Search and filter no-results states must provide a way to clear or reset the query/filter.

• API failure states must not be presented as normal empty states. They should include a retry action when possible.

• Form validation errors must appear close to the relevant field and explain how to fix the issue.

• Permission errors must explain the access problem and provide a next step such as contacting an admin or returning to a safe page.

• Keep copy short, specific, and user-facing. Do not expose raw backend error messages to end users.

• Preserve the existing design system and reuse shared state components whenever possible.

• Check mobile layout for long copy and stacked actions.

十二、验收清单：怎么判断 Codex 改得对不对

Codex 改完后，不要只看 diff。你需要按状态触发路径逐项验收。

• 首次进入功能页时，是否能看懂这个功能的价值？

• 搜索不到结果时，是否明确说明与当前关键词或筛选条件有关？

• 接口失败时，页面是否显示为错误状态，而不是普通空状态？

• 错误提示是否靠近出错位置，尤其是表单字段？

• 每个状态是否至少有一个明确下一步？

• 文案是否避免“系统错误”“参数错误”“未知异常”这类技术表达？

• 移动端是否没有文字溢出、按钮挤压、图标过大？

• Toast 是否没有被滥用为所有错误的唯一载体？

• 组件是否复用，没有在多个页面重复写同样的空状态结构？

• lint、typecheck、build 是否通过？如果有 Storybook 或 Playwright，是否补充了状态用例？

十三、常见错误：不要让 Codex 这样改

Codex 很适合做这类体验整理，但如果指令边界不清，也容易出现几个问题。

十四、达灵感页面可以怎么承接这类搜索

这篇文章适合承接几类用户搜索：

• 设计师搜索“怎么检查页面空状态是否完整”。

• 独立开发者搜索“怎么让 Codex 优化前端体验”。

• 产品负责人搜索“错误提示怎么写更清楚”。

• 前端工程师搜索“Codex 怎么统一 EmptyState / ErrorState 组件”。

达灵感可以在文末引导用户复制上面的任务指令，或进入对应的任务模板页，例如“Codex UI 体验审查模板”“Codex 错误状态优化模板”“Codex 表单文案检查模板”。这样文章不是单纯内容页，而是任务入口页。

十五、FAQ

Q1：Codex 能不能直接帮我设计空状态插画？

可以让它给出插画需求、组件结构和占位方案，但如果你对品牌插画风格要求很高，最好由设计师定义视觉规则，再让 Codex 落到代码。不要让它随意新增不统一的插画。

Q2：空状态和错误状态最重要的区别是什么？

空状态通常表示“现在没有内容，但系统没有失败”；错误状态表示“内容应该出现，但因为某种问题没有出现”。这两类状态的文案和按钮不能混用。

Q3：为什么不要只用 Toast 显示错误？

Toast 容易消失，用户不一定能把它和具体出错位置关联起来。表单字段错误、模块加载失败、页面级失败都应该有更稳定的位置。

Q4：Codex 修改这类问题会不会影响业务逻辑？

如果指令写得太泛，可能会。更安全的方式是要求它先输出审查报告，再分批改状态组件和文案，并明确“不改变业务逻辑”。

Q5：这类优化适合放进 AGENTS.md 吗？

适合。空状态和错误提示是长期规范，不是一次性任务。把规则写进 AGENTS.md 后，Codex 后续新增页面时更容易保持一致。

结语：让 Codex 处理“产品不顺利时”的体验

优秀的产品不只是在成功路径里显得顺畅，也要在没有数据、找不到结果、接口失败、权限不足、填写错误时仍然清楚。空状态和错误提示就是这些“不顺利时刻”的产品说明书。

让 Codex 帮你优化这件事，关键不是让它写几句更好听的文案，而是让它进入项目，找到状态判断，统一组件，补齐缺失场景，按用户能理解的方式给出下一步。这样改出来的不是表面文案，而是真实的产品成熟度。

发布建议

• 建议内链：Codex 检查网站 UI 问题、Codex 检查按钮文案和点击路径、Codex 做上线前代码审查、Codex 根据现有页面提取设计系统。

• 建议配图：一张“坏状态 vs 好状态”的对比图，左侧是“暂无数据 / 请求失败”，右侧是具体原因、说明和操作按钮。

• 建议 CTA：复制本文提示词，让 Codex 对你的项目做一次空状态和错误提示体检。

参考资料（内部核对用，可发布时删除）

• OpenAI Developers：Codex web。说明 Codex 是可以读取、编辑并运行代码的 coding agent。

• OpenAI Developers：Codex Best Practices。强调任务提示应包含 Goal、Context、Constraints、Done when，并建议复杂任务先计划。

• Nielsen Norman Group：Error-Message Guidelines。强调错误提示要可见、靠近错误源，并帮助用户恢复。

• Shopify Polaris：Empty state / Inline error。将空状态视为解释和引导用户继续前进的机会，字段错误应保持简短且贴近上下文。

• Material Design：Empty states / Interaction states。强调状态需要传达组件或界面的当前交互状态。