几个容易踩坑的点#

1. file:// 协议的 Origin 是 null：用 file:// 加载本地 HTML 再去请求 https://api.example.com，几乎所有服务器都会拒绝。
2. webSecurity 默认开启：Electron 默认行为和浏览器一致，渲染进程的请求会受 CORS 约束。
3. 自定义协议（如 app://）有自己的 Origin 规则：注册协议时如果没声明为 standard 或 secure，行为可能与预期不符。

场景 1：渲染进程直连远程 API#

1
// renderer.js  ❌ 经常会被 CORS 拦截
2
fetch('https://api.example.com/users')
3
  .then(r => r.json())

如果服务器没有为你的 Origin（可能是 file://、app://your-app 或开发用的 http://localhost:3000）配置 CORS，请求会失败。

场景 2：开发环境加载 dev server#

开发时通常用 Vite/Webpack 的 dev server（如 http://localhost:5173）作为渲染层，再去访问后端 API（如 http://localhost:8000）——典型的跨域。

场景 3：嵌入第三方 iframe#

某些第三方页面通过 X-Frame-Options 或 CSP 拒绝被嵌入，这虽然不是经典 CORS，但常被一起讨论。

场景 4：访问需要 Cookie 的服务#

跨域 + 携带 Cookie 需要服务端 Access-Control-Allow-Credentials: true 且 Allow-Origin 不能是 *，配置很容易出错。

方案 1：在主进程发起请求（✅ 最推荐）#

思路：渲染进程通过 IPC 把请求”代理”给主进程，由主进程用 Node 的 net 模块或 fetch 发起。主进程不受 CORS 约束。

1
const { ipcMain, net } = require('electron')
2

3
ipcMain.handle('api:request', async (_, { url, options }) => {
4
  const response = await net.fetch(url, options)
5
  return {
6
    status: response.status,
7
    data: await response.json(),
8
  }
9
})

1
const { contextBridge, ipcRenderer } = require('electron')
2

3
contextBridge.exposeInMainWorld('api', {
4
  request: (url, options) => ipcRenderer.invoke('api:request', { url, options }),
5
})

1
const result = await window.api.request('https://api.example.com/users')

优点：

• 安全：渲染进程仍保持沙箱
• 灵活：可以在主进程做缓存、鉴权、错误统一处理
• 与 contextIsolation: true 完全兼容

缺点：需要为每类请求设计 IPC 接口，初期工作量稍大。

方案 2：使用 session.webRequest 修改响应头#

思路：在主进程中拦截响应，注入 Access-Control-Allow-Origin 等头部，“骗过”渲染进程的 CORS 检查。

1
const { session } = require('electron')
2

3
app.whenReady().then(() => {
4
  session.defaultSession.webRequest.onHeadersReceived(
5
    { urls: ['https://api.example.com/*'] },
6
    (details, callback) => {
7
      callback({
8
        responseHeaders: {
9
          ...details.responseHeaders,
10
          'Access-Control-Allow-Origin': ['*'],
11
        },
12
      })
13
    }
14
  )
15
})

适用场景：你无法改服务端、又想让渲染进程直接发请求时。

注意：

• 仅修改响应头，不影响实际网络请求；如果服务端本身拒绝了请求（比如校验 Referer），仍然失败
• 通配 * 不允许携带 Cookie，需要 credentials 时要回填具体 Origin

方案 3：注册自定义协议（protocol.handle）#

思路：用 app:// 之类的协议加载页面，并把它声明为安全/标准协议，避免 file:// 的 Origin 为 null 的问题。Electron 28+ 推荐使用新的 protocol.handle API。

1
const { app, protocol, net } = require('electron')
2
const path = require('node:path')
3
const { pathToFileURL } = require('node:url')
4

5
protocol.registerSchemesAsPrivileged([
6
  { scheme: 'app', privileges: { standard: true, secure: true, supportFetchAPI: true } },
7
])
8

9
app.whenReady().then(() => {
10
  protocol.handle('app', (request) => {
11
    const url = new URL(request.url)
12
    const filePath = path.join(__dirname, 'dist', url.pathname)
13
    return net.fetch(pathToFileURL(filePath).toString())
14
  })
15
})

加载时使用 mainWindow.loadURL('app://index.html')，渲染进程的 Origin 就变成了 app://...，可以和后端配置正常的 CORS 白名单。

方案 4：开发环境配置代理#

仅针对开发期，通过 Vite/Webpack dev server 的 proxy 把 API 请求转发到后端，绕开跨域：

1
export default {
2
  server: {
3
    proxy: {
4
      '/api': {
5
        target: 'http://localhost:8000',
6
        changeOrigin: true,
7
      },
8
    },
9
  },
10
}

生产环境仍需采用方案 1、2 或 3。

方案 5：关闭 webSecurity（⚠️ 强烈不推荐）#

1
new BrowserWindow({
2
  webPreferences: {
3
    webSecurity: false, // 关闭同源策略
4
  },
5
})

不要这样做，原因：

• 同时关闭了同源策略、混合内容检查等多项安全机制
• 一旦渲染进程加载了不可信内容（广告、第三方 iframe、被注入的脚本），攻击面会显著扩大
• Electron 官方明确将其列为反模式

只有在内部工具、且加载内容完全可控时，才可以临时使用。