Excalidraw CORS配置避坑指南

Excalidraw CORS配置避坑指南

在企业级协作工具日益普及的今天，Excalidraw 凭借其手绘风格、轻量化架构和强大的可扩展性，已成为技术团队绘制架构图、流程设计和头脑风暴的首选白板工具。然而，当我们将它从公开演示环境迁移到私有部署或嵌入到内部系统时，一个看似简单却极易被忽视的问题浮出水面——CORS（跨域资源共享）错误。

你可能已经经历过这样的场景：前端页面加载正常，用户可以自由绘图，但一旦尝试上传图片、导出 SVG 或启用实时协作，控制台就抛出一连串红色错误：“No ‘Access-Control-Allow-Origin’ header is present”。更糟的是，这些问题往往在开发环境一切正常，直到上线才暴露出来。

这背后的核心矛盾在于——Excalidraw 的前端是静态的，而它的能力依赖于动态后端服务。当你把 UI 部署在一个域名下，而后端 API 运行在另一个地址时，浏览器的安全机制立刻介入，阻止了这些“跨源”请求。

要真正解决这个问题，不能只靠堆叠*通配符应付了事，而是需要理解整个通信链路中每个环节的角色与责任。

理解 CORS：不只是加个响应头那么简单

很多人对 CORS 的第一反应是：“后端加个Access-Control-Allow-Origin: *不就行了吗？” 可惜，现实远比这个复杂得多，尤其是在涉及凭证、自定义头部或 WebSocket 协议时。

CORS 实际上是一套由浏览器强制执行的协商机制。当你的 Excalidraw 前端运行在https://whiteboard.company.com，而试图调用https://api.draw.internal/upload-image接口时，浏览器会立即判断这是一次跨源请求，并根据请求类型决定是否启动预检流程。

简单请求 vs. 预检请求：关键分水岭

并不是所有请求都会触发 OPTIONS 探测。只有满足以下条件的才是“简单请求”：

• 方法为 GET、POST 或 HEAD；
• Content-Type 仅限于application/x-www-form-urlencoded、multipart/form-data或text/plain；
• 不携带自定义头部（如Authorization）；
• 不使用credentials: 'include'。

一旦你发送的是带 JWT 的 POST 请求，或者用了fetch中的credentials: include来传递 Cookie，哪怕目标 URL 就在同一域名下，只要协议/端口不同，浏览器就会先发一个 OPTIONS 请求来“探路”。

这意味着，如果你的后端没有正确响应这个 OPTIONS 请求，主请求根本不会发出。这也是为什么很多开发者看到“OPTIONS 404 Not Found”，误以为是路由问题，其实是忘了为这些路径开放预检支持。

凭证带来的限制：别再用*了

最典型的陷阱出现在需要身份认证的场景。假设你在上传图片时通过 Cookie 携带 session 信息：

fetch('/api/upload-image', { method: 'POST', body: formData, credentials: 'include' // ← 关键点！ });

此时，即便你设置了Access-Control-Allow-Origin: *，浏览器依然会拒绝该请求。因为 W3C 规范明确规定：当请求包含凭据时，服务器必须指定确切的源，不能使用通配符*。

正确的做法是：

Access-Control-Allow-Origin: https://whiteboard.company.com Access-Control-Allow-Credentials: true

这也意味着你需要在服务端实现 Origin 白名单校验逻辑，而不是无差别放行。

Excalidraw 的通信模型：哪些操作会触雷？

虽然 Excalidraw 本身是一个纯前端应用，但在实际使用中，以下几个功能模块几乎必然涉及跨域请求：

尤其是图像上传这一环，最容易踩坑。因为它同时具备多个“高危特征”：

• 使用multipart/form-data编码；
• 可能携带认证凭据；
• 文件较大，超时设置不当易失败；
• 若使用 CDN 回调，还可能涉及二次跨域。

举个真实案例：某团队将 Excalidraw 嵌入 Confluence，前端走 HTTPS，后端上传接口却是 HTTP 内网地址。结果不仅 CORS 报错，还会因混合内容（mixed content）被浏览器直接拦截——连 OPTIONS 都没机会发出。

典型部署结构中的隐藏雷区

我们来看一种常见的私有部署架构：

graph LR A[Client Browser] --> B[Nginx Proxy] B --> C[excalidraw/frontend container] B --> D[Custom Backend Service] D --> E[Image Storage / CDN]

表面上看，所有流量都经过 Nginx 统一代理，前端访问/，后端走/api/*，似乎属于“同源”。但实际上，这种架构仍有多个潜在断裂点。

反向代理 ≠ 跨域豁免

即使 Nginx 将/api/upload-image代理到内部服务，如果那个内部服务本身未开启 CORS 支持，仍然可能导致问题。原因在于：

1. 浏览器发送 OPTIONS 到/api/upload-image
2. Nginx 正确转发到后端
3. 后端返回 200 OK，但没有 CORS 头
4. 浏览器判定预检失败，主请求不再发出

解决方案不是让 Nginx 添加响应头（虽然可行），而是应在业务服务层明确处理 CORS，确保调试时直接访问 IP 也能工作。

WebSocket 升级失败：别忽略 Connection 头

实时协作依赖 WebSocket，而它的跨域规则与 HTTP 略有不同。除了协议必须匹配（HTTPS → WSS），你还得确保反向代理正确处理连接升级。

Nginx 配置示例：

location /socket { proxy_pass http://collab-service:3001; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection "upgrade"; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }

缺少Upgrade和Connection头会导致握手失败，报错"Error during WebSocket handshake"。这不是 CORS 错误，但效果一样——协作功能瘫痪。

iframe 嵌入：双重安全策略围堵

如果你想把 Excalidraw 嵌入 Confluence、Notion 或自研门户系统，还得面对另一重防护：X-Frame-Options和Content-Security-Policy。

默认情况下，许多 Web 服务器会添加：

X-Frame-Options: SAMEORIGIN

这就意味着它只能被同源页面嵌套。若你在https://portal.company.com中用 iframe 加载https://whiteboard.company.com，页面将显示为空白。

修复方式有两种：

1. 修改响应头允许特定来源：
   nginx add_header X-Frame-Options "ALLOW-FROM https://portal.company.com" always;

   ⚠️ 注意：ALLOW-FROM在现代浏览器中已被弃用。

2. 使用更现代的 CSP 方式：
   nginx add_header Content-Security-Policy "frame-ancestors 'self' https://portal.company.com;" always;

推荐后者，它是目前唯一标准化且广泛支持的方法。

如何构建生产级的 CORS 配置？

光知道问题在哪还不够，我们需要一套可持续维护、安全可控的解决方案。

1. 明确受信任源列表

永远不要在生产环境中使用Access-Control-Allow-Origin: *，尤其当你启用了凭据支持。建议的做法是：

const allowedOrigins = [ 'https://whiteboard.company.com', 'https://portal.company.com', 'https://confluence.company.com' ]; app.use(cors({ origin: (origin, callback) => { if (!origin || allowedOrigins.includes(origin)) { callback(null, true); } else { console.warn(`Blocked CORS request from untrusted origin: ${origin}`); callback(new Error('Not allowed by CORS')); } }, credentials: true }));

这样既能防止任意站点调用你的 API，又能保留日志追踪能力。

2. 启用预检缓存，减少冗余请求

每次复杂请求前都要发一次 OPTIONS？那性能可就拖累了。好在你可以通过Access-Control-Max-Age缓存预检结果：

app.use(cors({ maxAge: 86400 // 缓存 24 小时 }));

这样一来，同一来源对同一路径的预检只需执行一次，后续请求直接放行，显著降低延迟。

3. 开发环境友好适配

开发阶段频繁切换前后端容易引发本地 CORS 问题。推荐使用 Vite 或 Create React App 提供的代理功能，在.env.development.local中配置：

REACT_APP_PROXY_TARGET=http://localhost:8080

并在vite.config.js中设置：

export default defineConfig({ server: { proxy: { '/api': { target: 'http://localhost:8080', changeOrigin: true, }, '/socket': { target: 'ws://localhost:8080', ws: true, } } } })

这样前端开发服务器会自动转发请求，避免浏览器层面的跨域检查。

总结：从“避坑”到“筑堤”

Excalidraw 本身并不制造 CORS 问题，但它暴露了我们在微服务化、前后端分离架构中长期忽略的一个事实：网络边界正在变得越来越模糊。

我们不能再假设“只要在同一域名下就安全”，也不能指望一个*就能解决问题。真正的稳定性来自于对每一个通信环节的清晰认知与主动控制。

当你下次部署 Excalidraw 时，不妨问自己几个问题：

• 我的前端和后端真的“同源”吗？（协议、主机、端口）
• 所有 API 端点都支持 OPTIONS 预检吗？
• WebSocket 是否使用 WSS 并正确代理？
• iframe 嵌入是否允许？CSP 设置是否到位？
• 凭据传输是否关闭了通配符？是否有日志监控非法 Origin？

把这些检查项纳入 CI/CD 流程，甚至编写自动化探测脚本，才能真正做到防患于未然。

最终你会发现，解决 CORS 的过程，其实是在重新审视整个系统的信任模型。而这，正是构建可靠协作平台的第一步。