Vite项目搭建AIGC图片工作台：生图轮询与动态特效

从 Vite 空项目到 AIGC 图片工作台：打通生图、任务轮询、生成库与 Canvas 动态特效

很多 AIGC 项目的第一版，往往只有一个输入框：用户输入 Prompt，前端调用模型接口，页面显示一张图片。这个流程足以验证模型能力，但离真正的应用还有距离。真实项目还要面对异步任务、失败处理、接口密钥安全、图片链接过期、历史记录、文件下载，以及生成后的二次编辑。

最近从一个能正常运行的 Vite 空项目开始，逐步完成了一个名为 AIGC Creative Studio 的图片创作工作台。它目前已经打通了从 React 表单到 Express 创建本地任务，再到调用阿里云百炼万相、查询外部任务状态、下载并持久化图片、前端自动轮询、生成库管理、Canvas 图片编辑，以及 PNG/WebM 导出的完整流程。

这篇文章不只是展示最终效果，更会完整复盘开发的顺序、过程中遇到的问题，以及这个项目对前端和全栈能力有何帮助。

一、为什么要做这个项目

有前端、全栈和 HarmonyOS 开发经历，做过 Web 容器、Ja vaScript Bridge 和异步通信相关项目。在完成跨端运行时项目之后，希望再做一个更贴近当前应用方向的作品。这个项目需要满足几个条件：不是只展示静态页面；有真实的第三方 AI 服务；有前后端通信和异步任务；有文件处理与本地持久化；有能体现前端深度的交互；可以部署、演示，也可以继续扩展。

因此，选择了“AIGC 图片创作工作台”。没有一开始就创建复杂脚手架，也没有直接生成一个庞大的项目。第一步只是：npm create vite@latest，选择 React、TypeScript、ESLint。先让空项目正常启动，再一点点增加功能。这样做的好处是，每一步都知道自己加入了什么，也更容易定位问题。

二、技术栈

当前项目的主要技术栈如下：

前端： Vite、React、TypeScript、React Router、Canvas 2D API、MediaRecorder、原生 Fetch API。

后端： Node.js、Express、TypeScript、原生 Fetch API、本地 JSON 元数据存储、本地文件存储。

AIGC 服务： 阿里云百炼、万相文生图模型、异步任务接口。

没有在第一版引入 UI 组件库、Redux、数据库、Redis 和消息队列。不是因为这些技术没有价值，而是因为 MVP 阶段最重要的是先验证核心链路。

三、第一阶段：先做一个纯前端创作台

第一版页面只有三个区域。顶部导航展示项目名称、页面入口和后端服务状态。左侧参数面板包括 Prompt、Negative Prompt、图片比例、生成数量、Seed、风格预设和开始生成按钮。右侧结果区域根据任务状态展示空状态、提交中、等待处理、生成中、生成成功、生成失败。

表单状态最初直接使用 React useState 管理。这个阶段不接接口，只验证页面结构、响应式布局和交互状态。

这里有一个很实际的经验：结果区域要保持稳定高度。如果空状态、加载状态、失败状态和图片状态的高度完全不同，轮询期间整个页面会不断跳动。按钮文字从“刷新状态”变成“查询中”时，如果没有设置稳定宽度，也会造成明显抖动。因此，后来做了两项调整：结果区域设置稳定的最小高度；状态按钮设置固定宽度，并区分自动轮询状态与手动查询状态。

四、第二阶段：建立最小后端

前端页面稳定后，在项目中增加 server 目录，使用 Express 和 TypeScript 搭建后端。第一个接口不是生图，而是健康检查：GET /api/health，响应：{"success": true, "message": "AIGC Creative Studio API is running"}。然后让前端导航栏显示服务检测中、服务正常、服务未连接。

这个接口看起来简单，但它验证了第一条真正的全栈链路：React → Fetch → Express → JSON → React 状态。

后来增加路由时，还遇到过一个问题：/create 页面显示“服务未连接”，而 /library 页面显示“服务正常”。原因不是后端不稳定，而是两个页面分别维护了一份健康检查状态。最终把 Header 放到公共布局中，只保留一份应用级状态。推荐结构如下：BrowserRouter → AppLayout → Header 和 Routes（CreatePage、LibraryPage、EditorPage）。服务状态属于整个应用，不应该分别散落在页面组件里。

五、生成任务为什么不能只返回一张图片

真实生图通常不是立即完成的。请求提交到模型平台后，平台先返回一个任务 ID，任务状态随后经历 PENDING → RUNNING → SUCCEEDED / FAILED。因此，后端不能把它设计成普通同步接口。

项目中的本地任务状态为：'pending' | 'processing' | 'succeeded' | 'failed'。创建接口：POST /api/generations，查询接口：GET /api/generations/:taskId。前端提交参数后，后端立即创建本地任务，返回 {"success": true, "data": {"taskId": "本地任务 ID", "status": "pending"}}，随后由后端调用模型服务，并更新本地任务状态。这样做的好处是，前端只需要理解自己系统的任务协议，不需要直接依赖某一家模型平台的字段。

六、Provider 抽象：不要把业务代码绑死在模型平台上

在接入真实万相接口之前，先定义了 Provider 接口：interface ImageGenerationProvider { readonly name: string; generate(input: GenerateImageInput): Promise }。业务层只关心输入生成参数、等待生成结果、得到图片数组。至于底层使用万相、OpenAI Images、本地 Stable Diffusion，还是其他服务，由 Provider 负责。这层抽象解决了两个问题：第三方接口字段不会污染业务路由；以后替换模型时，不需要重写任务和生成库。

当前使用的是 WanxImageProvider，主要负责：读取环境变量、创建万相异步任务、查询任务状态、映射图片比例、处理超时和错误、提取图片 URL、转换为项目内部统一结果。为了避免开发期间意外消耗额度，还增加了安全开关 ENABLE_REAL_GENERATION=false，需要真实生成时才设置为 true。这不是模型平台要求的字段，而是项目自己的成本保护机制。

七、接入阿里云百炼万相

测试阶段选择了成本较低、带有新人免费额度的万相文生图模型。后端环境变量示例：PORT=3001、DASHSCOPE_API_KEY=、DASHSCOPE_MODEL=wanx2.0-t2i-turbo、DASHSCOPE_BASE_URL=https://dashscope.aliyuncs.com/api/v1、ENABLE_REAL_GENERATION=false。真实 .env 不应该提交到 Git。万相旧版文生图使用异步流程：创建任务 → 获得外部 task_id → 定时查询 → 获取图片 URL。Provider 内部将外部状态映射为项目状态：PENDING → pending、RUNNING → processing、SUCCEEDED → succeeded、FAILED → failed。前端则根据本地 taskId 自动轮询：等待处理 → 生成中 → 生成完成。任务进入 succeeded 或 failed 后立即停止轮询。组件卸载、任务变化或重新生成时，也会清理旧定时器。这里需要注意：轮询不是越快越好，频率过高会增加服务器和第三方接口压力，甚至触发限流。

八、失败信息必须真正展示出来

最初失败时，页面只显示“生成失败，请稍后重试”，这对用户和开发者都不够友好。后来任务增加了结构化错误：{"code": "REAL_GENERATION_DISABLED", "message": "Real image generation is disabled", "retryable": false}。前端失败卡片展示：生成失败、错误原因、可选错误码、重新生成按钮。但不能把以下内容返回给用户：API Key、Authorization、服务器绝对路径、完整异常堆栈、第三方敏感响应。好的错误处理，不只是 catch 一下，而是要在安全与可诊断性之间取得平衡。

九、为什么必须把图片下载到本地

模型服务返回的图片通常是临时 URL。如果生成库直接保存这个 URL，过一段时间后，历史图片就会全部失效。因此，Provider 成功后，后端立即执行：读取临时 URL → 下载图片二进制 → 保存到 storage/images → 将任务中的 URL 替换为本地地址。本地地址示例：/api/images/{taskId}-0.png。任务元数据保存到 server/data/generations.json，结构类似：包含 taskId、status、request（prompt、negativePrompt、aspectRatio、count、style）、result（images 数组，其中 url 为本地地址）。服务启动时重新读取 JSON，恢复历史任务。当前阶段使用 JSON 是为了快速完成 MVP，它不适合多实例和高并发写入，后续计划迁移 PostgreSQL；图片则可以从本地目录迁移到 OSS。

十、生成库：让“生成历史”真正有意义

最初导航栏同时出现了“生成库”和“生成历史”，实际功能完全重合。后来删除重复入口，只保留“图片创作 | 生成库 | 服务状态”。生成库接口：GET /api/generations?status=succeeded&limit=20&offset=0。生成库展示：图片、Prompt、风格、图片比例、生成时间、下载、新窗口查看、编辑、删除。图片下载没有直接依赖第三方 URL，而是通过后端下载接口：GET /api/generations/:taskId/images/:imageIndex/download。后端只能读取任务中已有的图片地址，不接受用户提交任意 URL，从而降低 SSRF 风险。删除功能同样需要同时处理两部分：删除本地图片文件 + 更新任务元数据。如果一个任务的最后一张图片被删除，则一并清理任务记录。

十一、Canvas 编辑器：项目真正有辨识度的部分

单纯调用生图 API，更多体现接口集成能力。为了增加前端技术深度，又加入了 Canvas 编辑器。路由：/editor/:taskId/:imageIndex。编辑器会：根据任务 ID 查询任务；找到指定图片；加载本地图片；绘制到原始分辨率的 Canvas；在页面中按容器尺寸缩放显示。页面看到的是缩放后的 Canvas，但导出时仍使用原始分辨率，避免把页面显示尺寸误当成图片输出尺寸。

十二、黑白滤镜与灰度渐变

黑白滤镜不是简单使用 CSS filter: grayscale(1)，而是真正处理 Canvas 像素。灰度值计算：gray = 0.299 × red + 0.587 × green + 0.114 × blue。强度混合：result = original × (1 - intensity) + gray × intensity。每次调整都从原始 ImageData 重新计算，不能基于上一次处理结果继续计算，否则来回拖动后会累计失真。在此基础上，又实现了“灰度到彩色”的横向渐变：左侧黑白、右侧彩色、中间平滑过渡，可以拖动分界位置，可以调节过渡宽度。过渡使用 smoothstep：t = clamp((x - start) / (end - start), 0, 1)，smooth = t × t × (3 - 2 × t)，最后使用 smooth 混合彩色与灰度值。

十三、动态雨滴与“雨滴唤醒色彩”

普通静态雨丝可以通过 Canvas 绘制半透明线段完成，但项目中更有辨识度的效果是：整张图片变灰 → 用户设置雨滴落点 → 雨滴从顶部落下 → 落点出现涟漪 → 涟漪覆盖区域恢复原图色彩。这个效果使用两份离屏画布：colorCanvas（彩色原图）和 grayscaleCanvas（灰度图片）。每一帧：主画布绘制灰度底图；绘制下落雨滴；雨滴到达目标点后进入涟漪阶段；使用圆形裁剪区域绘制彩色图层；绘制逐渐扩散并淡出的涟漪圆环。

伪代码如下：ctx.drawImage(grayscaleCanvas, 0, 0); ctx.sa ve(); ctx.beginPath(); ctx.arc(centerX, centerY, radius, 0, Math.PI * 2); ctx.clip(); ctx.drawImage(colorCanvas, 0, 0); ctx.restore();。动画使用 requestAnimationFrame，并通过 deltaTime 更新位置，避免不同刷新率下动画速度不一致。此外还需要处理：切换工具时取消动画；组件卸载时取消动画；页面不可见时暂停；React StrictMode 下避免双动画循环；动画数据放在 useRef，不在每一帧触发 React 渲染。

十四、PNG 与 WebM 导出

Canvas 当前画面可以通过 canvas.toBlob() 导出 PNG。但 PNG 只能保存静态瞬间。为了保存完整的雨滴与涟漪动画，项目又使用 canvas.captureStream(30) 配合浏览器原生 MediaRecorder 导出 WebM。大致流程：重置动画 → captureStream 获取 Canvas 视频流 → MediaRecorder 开始录制 → 播放雨滴与涟漪动画 → 动画完成后保留最终画面 → 停止录制 → 合并 Blob → 下载 WebM。格式选择需要逐级检测：video/webm;codecs=vp9、video/webm;codecs=vp8、video/webm。不能默认所有浏览器都支持 VP9。录制结束后，还必须清理：MediaStream Track、MediaRecorder、Blob URL、超时定时器、requestAnimationFrame。

十五、编辑后的图片如何回到生成库

Canvas 编辑完成后，除了本地下载，还可以保存回生成库。前端通过 canvas.toBlob() 得到 PNG，再发送：POST /api/generations/:taskId/images/:imageIndex/edits，Content-Type: image/png。后端使用路由级 express.raw() 接收二进制，校验：Content-Type、文件大小、PNG 文件头、原任务、原图片索引、存储路径。编辑后的图片不会覆盖原图，而是作为新资产追加：AI 生成图 → 编辑作品。生成库中可以继续查看、下载和再次编辑。至此，项目形成完整闭环：生成 → 保存 → 浏览 → 编辑 → 导出 → 再保存 → 删除。

十六、开发中遇到的几个典型问题

1. .env 明明存在，却读取不到。 曾经执行 node -e "require('dotenv').config(); console.log(process.env.ENABLE_REAL_GENERATION)"，结果是 undefined。最终发现配置没有正确写入真实的 server/.env，或者文件名实际是 .env.txt。排查环境变量时，不要直接打印 API Key，可以只判断是否存在：Boolean(process.env.DASHSCOPE_API_KEY)。

2. 健康检查正常，生图却提示无法连接。 增加 React Router 后，如果请求写成 fetch('api/generations')，在 /create 页面可能被解析为 /create/api/generations。因此统一封装了 API Base URL：VITE_API_BASE_URL=http://localhost:3001，所有健康检查、任务创建、轮询、图片地址和下载地址都通过同一个方法拼接。

3. 图片能在 Network 看到，却不能在页面下载。 跨域图片使用 时，浏览器不一定直接下载。因此增加后端下载袋里，只下载任务中已经保存的本地图片，再设置 Content-Disposition: attachment。