摘要
让 Codex 写一个上传组件并不难，难的是把上传限制、错误处理、接口调用、进度展示和测试验证全部做完整。本文以后台管理系统的文件上传功能为例，分享如何把真实需求拆成可执行任务，并让 Codex按照“分析项目、设计方案、修改代码、运行测试、检查 Git Diff”的流程完成交付。
很多开发者第一次使用 Codex 做项目时，习惯直接输入：
帮我做一个文件上传功能。这样的任务看起来明确，实际上仍然缺少很多关键信息。
例如：
允许上传什么格式；
文件大小限制是多少；
是否支持多文件；
是否需要显示进度；
上传失败后能否重试；
上传成功后返回什么；
是否需要删除已上传文件；
接口是否已经存在；
项目有没有可复用组件；
修改完成后运行什么测试。
如果这些问题没有提前说明，Codex 可能生成一个“可以运行”的组件，但未必适合当前项目。
下面以一个 Vue 3 后台管理项目为例，演示完整的任务流程。
一、先把需求写成验收标准
假设产品需求是：
商品编辑页面支持上传一张商品主图。
不要直接开始写代码，先把需求转换成可以验证的标准。
功能目标： 在商品编辑页面增加主图上传功能。 验收标准： 1. 只允许上传 JPG、PNG 和 WebP； 2. 单个文件不能超过 5MB； 3. 一次只能上传一张图片； 4. 上传过程中显示进度； 5. 上传失败时显示明确原因； 6. 上传成功后显示预览图； 7. 用户可以删除并重新上传； 8. 保存商品时提交图片地址； 9. 不修改现有商品保存接口的其他字段； 10. 类型检查、测试和构建必须通过。这一步非常重要。
因为“完成上传功能”和“满足全部验收标准”是两件不同的事情。
二、让 Codex 先分析现有项目
真实项目通常已经存在：
请求封装；
消息提示组件；
表单组件；
图片预览组件；
文件上传接口；
公共类型定义。
如果不先分析，Codex 很可能重复开发。
推荐先输入：
请分析当前项目，不要修改代码。 本次目标是在商品编辑页面增加主图上传功能。 请重点检查： 1. 商品编辑页面所在文件； 2. 商品表单的数据结构； 3. 是否已有上传接口； 4. 是否已有上传组件； 5. 请求拦截器如何处理错误； 6. 消息提示组件如何使用； 7. 商品保存接口如何提交图片字段； 8. 当前测试框架和验证命令； 9. 预计需要修改哪些文件。 先输出分析结果和实现建议。假设 Codex 分析后发现：
相关文件： - src/views/product/Edit.vue - src/api/upload.ts - src/api/product.ts - src/types/product.ts - src/components/ImageUploader.vue - tests/product/Edit.test.ts 现有能力： - 已有单文件上传接口； - 已有公共消息提示方法； - 商品类型中已经存在 coverUrl 字段； - 项目没有可复用的图片上传组件。这说明本次任务不需要新增上传接口，只需要完成组件和页面接入。
三、先确定修改范围
接下来要限制 Codex 的操作范围。
本次允许修改： - src/components/ImageUploader.vue - src/views/product/Edit.vue - src/types/product.ts - tests/product/Edit.test.ts - tests/components/ImageUploader.test.ts 禁止修改： - src/api/upload.ts - src/api/product.ts - 路由配置 - 权限模块 - package.json - Lock 文件 要求： - 不新增第三方依赖； - 不全局格式化； - 优先复用现有请求和提示方法； - 如必须修改范围外文件，先说明原因。这一步可以避免 AI 顺手调整接口、依赖或其他业务页面。
四、把功能拆成几个小步骤
不要让 Codex 一次写完所有内容。
可以把任务拆成五个阶段。
第一阶段：定义组件输入和输出
例如：
type ImageUploaderProps = { modelValue?: string; maxSizeMb?: number; disabled?: boolean; }; type ImageUploaderEmits = { "update:modelValue": [value: string]; error: [message: string]; };需要先确定：
页面怎么传入当前图片；
上传成功后怎么返回图片地址；
上传失败后怎么通知页面；
是否支持禁用状态。
组件接口确定后，再写内部逻辑。
第二阶段：实现文件校验
校验要发生在上传请求之前。
const allowedTypes = [ "image/jpeg", "image/png", "image/webp" ]; function validateFile(file: File): string | null { if (!allowedTypes.includes(file.type)) { return "仅支持 JPG、PNG 和 WebP 图片"; } const maxSize = 5 * 1024 * 1024; if (file.size > maxSize) { return "图片大小不能超过 5MB"; } return null; }重点是不要只检查扩展名。
虽然前端校验不能代替服务端安全校验，但可以提前拦截明显不符合要求的文件，减少无效请求。
第三阶段：接入上传接口
推荐让 Codex复用现有接口，而不是重新封装。
请使用项目现有的 uploadImage 方法。 上传流程： 1. 用户选择文件； 2. 执行格式和大小校验； 3. 校验通过后开始上传； 4. 显示上传进度； 5. 上传成功后读取返回的 URL； 6. 触发 update:modelValue； 7. 上传失败后恢复可操作状态； 8. 显示项目统一的错误提示。如果接口返回结构不明确，应该先阅读类型和调用示例，不要凭经验猜测字段名称。
五、不要忽略上传状态
文件上传至少有以下几个状态：
type UploadStatus = | "idle" | "validating" | "uploading" | "success" | "error";不同状态对应不同界面：
idle：可以选择图片；validating：正在检查文件；uploading：显示进度，禁止重复提交；success：显示预览和删除按钮；error：显示失败信息，允许重新上传。
如果不管理状态，容易出现：
连续点击造成重复上传；
上传失败后按钮仍然禁用；
删除图片后进度没有重置；
用户保存表单时图片仍在上传。
可以补充一条业务规则：
如果图片仍处于上传状态，禁止提交商品表单，并提示用户等待上传完成。六、错误处理要覆盖多个场景
上传失败并不只有“网络错误”。
至少要考虑：
1. 文件格式不支持
前端直接拦截，不发起请求。
2. 文件大小超限
显示具体限制，例如“图片大小不能超过 5MB”。
3. 网络中断
恢复上传按钮，允许重新选择文件。
4. 服务端拒绝
读取接口返回的业务错误信息。
5. 登录状态失效
交给项目统一的请求拦截器处理，不要在上传组件内重复实现登录逻辑。
6. 返回数据异常
如果接口成功但没有返回图片地址，需要视为上传失败。
可以让 Codex检查：
请检查上传流程是否覆盖： - 不支持的格式； - 文件过大； - 网络错误； - 接口业务错误； - 登录失效； - 返回结果缺少 URL； - 用户重复点击； - 上传中删除图片； - 组件卸载时请求仍未完成。七、页面接入时不要破坏原有表单
上传组件完成后，需要接入商品编辑页面。
例如：
<ImageUploader v-model="form.coverUrl" :max-size-mb="5" :disabled="submitting" />商品保存时，仍然使用原来的表单结构：
await updateProduct({ ...form, coverUrl: form.coverUrl });这里需要重点检查：
coverUrl是否允许为空；编辑旧商品时能否显示原图；
删除图片后提交什么值；
上传完成前能否保存；
保存失败后是否保留图片；
返回列表再进入时数据是否正确。
不要为了增加上传功能，重写整个商品表单。
八、让 Codex 补齐测试
完成代码后，至少要覆盖以下测试。
文件校验测试
1. JPG 可以上传； 2. PNG 可以上传； 3. WebP 可以上传； 4. PDF 被拒绝； 5. 超过 5MB 的图片被拒绝； 6. 校验失败时不调用上传接口。上传状态测试
1. 上传开始后显示加载状态； 2. 上传中不能重复选择文件； 3. 上传成功后显示预览； 4. 上传失败后恢复按钮； 5. 删除图片后清空 modelValue； 6. 上传中不能提交商品表单。页面集成测试
1. 编辑旧商品时显示原主图； 2. 上传新图后更新 coverUrl； 3. 删除图片后表单字段清空； 4. 保存时提交正确的图片地址； 5. 商品其他字段保持不变。可以使用：
请按照项目现有测试风格补充测试。 不要为了让测试通过而降低断言标准，也不要跳过失败用例。九、运行完整验证
修改完成后，不要只检查页面能否打开。
至少运行：
npm run type-check npm run lint npm run test npm run build如果测试失败，先让 Codex 分析原因：
下面是验证失败日志。 请先判断： 1. 哪个步骤失败； 2. 是否由本次修改引起； 3. 是业务代码问题、测试问题还是环境问题； 4. 最小修复方案是什么。 先分析，不要直接放宽测试或关闭规则。十、最后检查 Git Diff
运行：
git status git diff --stat git diff重点检查：
是否修改了允许范围以外的文件；
是否新增了依赖；
是否改动上传接口；
是否影响其他商品字段；
是否有大面积格式化；
是否补充了测试；
是否留下调试日志；
是否正确处理错误状态。
还可以让 Codex输出交付报告：
请根据本次 Git Diff 输出交付总结。 包括： 1. 实现了哪些功能； 2. 修改了哪些文件； 3. 每个文件的修改目的； 4. 覆盖了哪些异常场景； 5. 新增了哪些测试； 6. 验证命令及结果； 7. 仍然存在的风险； 8. 是否有无关修改。十一、一个完整的任务提示词
下面这份模板可以直接用于类似项目。
任务： 在商品编辑页面增加单图片上传功能。 功能要求： - 支持 JPG、PNG、WebP； - 最大 5MB； - 一次只能上传一张； - 显示上传进度； - 支持预览、删除和重新上传； - 上传失败后允许重试； - 保存商品时提交图片 URL； - 上传中禁止保存商品。 工作流程： 1. 读取 AGENTS.md； 2. 分析现有商品表单和上传接口； 3. 找出可复用代码； 4. 输出实现方案和修改文件； 5. 等确认范围后再修改； 6. 按最小修改原则实现； 7. 补充组件和页面测试； 8. 运行类型检查、Lint、测试和构建； 9. 检查 Git Diff； 10. 输出交付报告。 禁止事项： - 不新增第三方依赖； - 不修改上传接口； - 不修改商品接口其他字段； - 不调整路由和权限； - 不全局格式化代码； - 不跳过测试。总结
让 Codex 完成真实项目任务，关键不是提示词写得多长，而是有没有提供清晰的工程流程。
一个可靠的文件上传任务，至少需要经过：
明确需求 → 分析项目 → 限定范围 → 拆分步骤 → 处理异常 → 补充测试 → 运行验证 → 检查 Git Diff。
如果只说“帮我做一个上传组件”，AI 很容易只完成最表面的代码。
当任务目标、修改范围、验收标准和验证方式都写清楚后，Codex 才能从代码生成工具，逐渐变成可以参与真实项目交付的开发助手。
对于偶尔修改单个文件的用户，轻量使用通常已经足够；如果每天都需要处理多文件任务、持续测试和完整仓库分析，再根据实际工作量评估更高版本会更合理。
CSDN 文章描述
如何让 Codex 完成一个真实开发任务？本文以商品图片上传功能为例，讲解需求拆解、项目分析、范围限制、异常处理、自动化测试、Git Diff 审查和代码交付流程。
参考资料
Vue.js 官方文档
TypeScript 官方文档
Vitest 官方文档
Git 官方文档
OpenAI Codex 使用文档