应采用服务端组件封装QClaw API调用逻辑：在app/api/qclaw/route.ts创建Route Handler转发文件流，在app/dashboard/page.tsx中用fetch调用并传参至客户端组件。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
如果您在Next.js App Router项目中尝试集成QClaw智能文档处理能力，但发现服务端组件无法直接调用QClaw SDK或出现运行时错误，则可能是由于QClaw客户端SDK依赖浏览器环境API（如fetch未被Node.js runtime完全兼容）、或未正确区分服务端与客户端执行上下文。以下是解决此问题的步骤：
一、使用服务端组件封装QClaw API调用逻辑
该方法利用App Router服务端组件天然支持异步操作的特性，在服务端发起对QClaw后端服务（如腾讯云QClaw REST API）的HTTP请求，避免将SDK带入客户端Bundle。服务端组件不打包至浏览器，可安全使用node-fetch或axios等服务端HTTP库。
1、在app/api/qclaw/route.ts中创建Route Handler，接收上传的文件流并转发至QClaw服务端接口。
2、在app/dashboard/page.tsx中定义服务端组件函数，使用await fetch调用上述Route Handler，获取结构化解析结果。
3、将解析后的JSON数据作为props直接传递给需要展示的客户端组件，例如<ParsedResultView data={result} />。
二、通过客户端组件加载QClaw Web SDK
该方法适用于需在浏览器中直接调用QClaw提供的Web SDK（如@tencentcloud/qclaw-web-sdk）进行前端预览、区域标注或实时OCR反馈的场景。必须显式声明'use client'以启用React客户端状态与事件系统。
1、在app/components/QClawUploaderClient.tsx文件顶部添加'use client';指令。
2、使用useState和useEffect管理文件选择、上传状态及QClaw SDK初始化生命周期。
3、调用QClawSDK.init({ secretId, secretKey, region })完成认证，并通过QClawSDK.parseDocument(file)触发解析。
4、将返回的taskId交由服务端轮询接口（如/api/qclaw/status/[id]）获取最终结果，避免客户端长连接阻塞。
三、构建中间层服务代理QClaw请求
该方法将QClaw调用完全隔离于Next.js应用之外，通过独立部署的Node.js或Edge Function服务统一处理鉴权、限流、重试与错误映射，Next.js仅作为轻量级消费端。此举提升安全性并规避服务端组件对敏感密钥的暴露风险。
1、部署一个独立的QClaw代理服务，监听POST /parse，接收multipart/form-data，调用QClaw OpenAPI并返回标准化响应体。
2、在Next.js服务端组件中使用fetch('https://your-proxy.com/parse', { method: 'POST', body: formData })发起请求。
3、代理服务负责注入X-TC-Action、Authorization等腾讯云必需头字段，并对429、503等错误码做统一退避重试。
4、Next.js端无需安装任何QClaw SDK包，彻底消除服务端组件与浏览器API兼容性冲突。
四、利用Server Actions触发QClaw解析流程
该方法结合Next.js 14+ Server Actions机制，在表单提交等用户交互后，由服务端直接执行QClaw解析任务，无需手动管理API密钥分发或客户端状态同步，适合文件上传后立即解析的典型业务流。
1、在app/actions.ts中定义async function parseWithQClaw(formData: FormData)，读取formData.get('file')为Uint8Array。
2、使用@aws-sdk/client-s3或腾讯云tencentcloud-sdk-nodejs将文件暂存至COS，生成临时URL供QClaw拉取。
3、调用QClaw StartDocParse接口传入COS对象URL，获取TaskId并存入数据库或缓存。
4、在页面组件中使用useFormState与useFormStatus绑定表单，提交后自动触发Server Action，无需额外配置use client或自定义Hook。
