Qoder跨域配置教程：全栈开发CORS解决方案
网页端唤醒QoderWake失败，本地开发中这个坑踩到的人不少——明明客户端已经装好，浏览器点击按钮却始终连不上，要么报“未检测到本地服务”，要么直接超时。排查一圈下来，十有八九是跨域请求被浏览器拦截。根本原因很直接：Web Bridge服务返回的响应头缺少Access-Control-Allow-Origin这些关键的CORS字段，或者前端请求的域名没被显式加入白名单。下面把完整修复流程拆开讲清楚，步骤不多，但每一步都容易掉进去。
核实QoderWake Web Bridge状态与端口监听
先别急着改配置，终端执行 qoderwake status，看输出有没有“WebBridge started on :8081”这一行。没有？说明Web Bridge模块压根没启动。直接敲 qoderwake restart --enable-web-bridge --web-port=8081，强制启用并绑定端口——这条命令会覆盖配置文件中的旧参数，确保服务以最新配置运行。
⚠️ 注意：如果你之前在config.yaml里手动配过web_bridge节点，这次强制重启会暂时忽略文件内容，重启成功后记得重新编辑配置文件把设置固化，否则下次服务重启又得手动加参数。
向config.yaml注入完整CORS响应头规则
进入QoderWake安装目录，找到 config.yaml，在 server: 节点下插入这段配置：
web_bridge:
enabled: true
port: 8081
allow_origin: ["http://localhost:3000", "https://qoder.com", "https://your-dev-site.com"]
allow_credentials: true
allowed_headers: ["Content-Type", "Authorization", "X-Qoder-Token"]
这里有个极易忽略的要点：allow_origin 必须精确列出所有合法的前端域名，绝对不能用 "*" 搭配 allow_credentials: true。一旦用了通配符，浏览器会拒绝携带Cookie或认证头的请求，唤醒直接失败。保存文件后，执行 qoderwake restart，观察日志末尾是否出现 “CORS headers enabled for origins [...]” 提示——这句话出现才代表配置生效。
前端请求显式声明withCredentials
网页端发送请求时，凭证传递必须显式开启。以Fetch API为例：
fetch("http://localhost:8081/wake", {
method: "POST",
credentials: "include",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ task: "open-editor" })
});
如果用XMLHttpRequest，写法如下：
const xhr = new XMLHttpRequest();
xhr.open("POST", "http://localhost:8081/wake");
xhr.withCredentials = true;
xhr.setRequestHeader("Content-Type", "application/json");
xhr.send(JSON.stringify({ task: "open-editor" }));
这一步太容易漏了——credentials: "include" 或 xhr.withCredentials = true 少写任何一个，浏览器就不会发送Cookie和认证信息。QoderWake服务端认不出用户身份，唤醒逻辑直接跳过，你还以为是服务端没响应。
验证跨域链路是否通畅
所有配置改完后，怎么确认通了呢？打开Chrome开发者工具的Network标签页，过滤出 wake 请求。点击网页上的唤醒按钮，观察这个请求的Response Headers里是否包含以下几项：
Access-Control-Allow-Origin: https://qoder.comAccess-Control-Allow-Credentials: trueAccess-Control-Allow-Methods: POST, OPTIONSAccess-Control-Allow-Headers: Content-Type, Authorization, X-Qoder-Token
如果看到OPTIONS预检请求，确认它的响应状态码是200，并且上述头字段一个都不少。最坑的是OPTIONS返回404，或者缺少Access-Control-Allow-Methods——这说明Web Bridge根本没能正确处理预检请求。等所有响应头校验通过，后续的POST请求返回200和{"status":"success"}，这时跨域唤醒链路才算真正打通。
