基于Cloudflare生态的应用部署与开发全解

基于Cloudflare生态的应用部署与开发全解一、项目背景本文档聚焦基于Cloudflare生态Workers、Pages、R2等核心能力构建的AI内容重写器项目汇总部署配置、功能开发、问题解决全流程关键内容核心解决跨域访问、域名路由、LLM模型集成等核心问题保障AI内容重写服务的稳定部署与高效运行。二、核心部署配置问题及解决方案2.1 Workers部署失败 - 自定义域名规则限制问题表现部署Workers时触发路由验证错误提示自定义域名不支持路径及通配符格式错误信息如下X [ERROR] Invalid Routes: [脱敏域名]/api/*: Wildcard operators (*) are not allowed in Custom Domains Paths are not allowed in Custom Domains根因分析Cloudflare自定义域名的路由规则中不支持在域名后拼接路径或使用通配符*作为路由匹配符。解决方案子域名分流方案放弃原域名路径通配符的配置形式改用独立子域名承载API服务如api.[脱敏主域名]统一域名透传方案采用主域名统一接入通过Pages路由透传规则实现前端与后端接口的路径隔离。2.2 DNS记录冲突问题表现添加自定义域名时提示域名已存在外部管理的DNS记录无法完成配置错误信息Hostname [脱敏域名] already has externally managed DNS records解决方案在Cloudflare控制台Dashboard中删除该域名下冲突的现有DNS记录或在添加自定义域的流程中选择“覆盖原有记录”选项完成配置。2.3 R2存储桶未启用问题表现部署过程中提示指定名称的R2存储桶未找到需先启用对应功能错误信息R2 bucket [脱敏存储桶名称] not found. Please enable R2 through the Cloudflare Dashboard. [code: 10042]解决方案临时移除配置文件中与R2存储桶相关的配置项优先完成核心服务部署后续在Cloudflare控制台手动启用R2功能并创建指定名称的存储桶再补全相关配置。三、跨域与API路径适配问题3.1 API请求404错误问题表现前端调用/auth/register等API接口时返回404错误核心原因为前后端API路径配置不匹配前端环境变量配置VITE_API_URLhttps://[脱敏子域名]后端Workers路由定义/api/auth/register。解决方案统一前后端API路径前缀修正前端环境变量配置# 正确配置示例 VITE_API_URLhttps://[脱敏子域名]/api3.2 统一域名透传架构配置为简化域名管理、降低跨域复杂度设计统一域名Pages路由透传的架构方案[脱敏主域名]/ → Pages前端页面 [脱敏主域名]/api/* → Workers后端接口通过_routes.json透传关键配置前端工程中新增web/public/_routes.json文件配置Pages路由透传规则实现/api路径下的请求转发至Workers扩展Workers的CORS跨域资源共享配置将前端主域名添加至允许列表确保跨域请求正常。四、LLM模型集成问题及优化4.1 模型访问权限与名称配置问题1模型访问被拒绝调用LLM模型时返回权限错误{code:Model.AccessDenied,message:Model access denied.}解决方案登录对应大模型平台控制台手动申请目标模型如qwen-plus的访问权限。问题2模型不存在错误调用模型时返回参数错误核心原因为模型名称格式不规范{code:InvalidParameter,message:Model not exist.}解决方案统一模型名称为小写格式示例配置LLM_MODEL qwen-plus-2025-12-014.2 LLM错误信息精细化透传为提升用户体验优化模型调用错误的处理逻辑解析平台错误码并返回人性化提示// 解析大模型平台错误码返回精准提示if(errorJson.codeInvalidApiKey){errorDetailAPI Key 无效或已过期请检查配置;}elseif(errorJson.codeInsufficientBalance){errorDetail账户余额不足请充值;}elseif(errorJson.codeInvalidModel){errorDetail模型${this.env.LLM_MODEL}不存在或不可用;}4.3 流式响应错误处理针对AI内容重写的流式响应场景优化错误捕获与透传逻辑确保前端能获取详细错误信息}catch(error){consterrorMessageerrorinstanceofError?error.message:Unknown error;consterrorDatadata:${JSON.stringify({error:Failed to rewrite content,details:errorMessage})}\n\n;controller.enqueue(encoder.encode(errorData));controller.close();}五、核心配置文件调整5.1 Workers部署配置wrangler.toml简化多环境配置块删除[env.dev]和[env.production]仅保留核心部署配置修正LLM模型名称配置统一为小写规范格式。5.2 前端环境配置.env.production从子域名方案迁移至统一域名方案简化API地址配置# 原配置子域名 VITE_API_URLhttps://[脱敏子域名]/api # 新配置统一域名 VITE_API_URL/api5.3 CORS跨域配置扩展允许的源地址列表覆盖本地开发、生产环境、子域名及Pages默认域名origin:[http://localhost:5173,https://[脱敏主域名],https://[脱敏子域名],https://[脱敏Pages默认域名].pages.dev]六、部署架构设计6.1 子域名分流架构基础方案用户 → [脱敏主域名] (Pages 前端) ↓ API 调用 → [脱敏子域名] (Workers 后端)6.2 统一域名透传架构优化方案用户 → [脱敏主域名] ├── / → Pages (前端页面) └── /api/* → Workers (后端接口Pages路由透传)七、前端功能开发优化7.1 多语言选择功能为满足多场景内容重写需求新增语言选择功能新增selectedLanguage状态管理选中的输出语言支持语言选项English / 中文 / Français / Deutsch将语言参数绑定至rewriteStream请求实现不同语言的内容重写输出。7.2 关键文件清单文件路径核心作用workers/wrangler.tomlWorkers部署配置模型、环境变量workers/src/services/llm.tsLLM模型调用逻辑含错误码解析workers/src/index.tsWorkers入口含CORS跨域配置web/.env.production前端生产环境API地址配置web/public/_routes.jsonPages路由透传规则配置web/src/views/Rewrite.vue重写功能页面含语言选择交互八、待完成配置与后续优化8.1 Cloudflare控制台待配置项Workers自定义域名添加api.[脱敏主域名]Pages自定义域名添加[脱敏主域名]R2存储桶可选启用R2功能并创建指定名称存储桶。8.2 功能优化建议权限管理完成大模型平台目标模型的访问权限开通错误监控集成Sentry或Cloudflare Logs实现错误监控性能优化前端代码分割减小打包体积提升加载速度。九、测试验证示例9.1 API健康检查curlhttps://[脱敏子域名]/health9.2 流式内容重写测试curl-XPOST https://[脱敏子域名]/api/rewrite/stream\-HContent-Type: application/json\-HAuthorization: Bearer [脱敏TOKEN]\-d{ text: Test content, style: professional, language: en }十、总结本次项目开发与部署核心完成以下目标解决Cloudflare Workers/Pages部署中的域名路由、DNS冲突等配置问题优化跨域访问策略支持子域名与统一域名两种架构方案完成LLM模型集成解决权限、名称格式、错误透传等核心问题实现多语言输出、流式响应错误处理等前端功能优化形成标准化的配置文件与测试验证流程。后续可重点推进控制台域名配置、模型权限开通及全链路测试确保服务稳定上线运行。