configuring-tauri-http-headers

Tauri HTTP 头部安全配置

本技能涵盖 Tauri v2.1.0+ 中的 HTTP 头部配置，让开发者能够为 webview 响应设置安全头部。

概述

Tauri 允许配置包含在 webview 响应中的 HTTP 头部。这些头部适用于生产构建，不会影响 IPC 消息或错误响应。

支持的头部（允许列表）

出于安全考虑，Tauri 将头部配置限制为特定的允许列表：

CORS 头部

• Access-Control-Allow-Credentials
• Access-Control-Allow-Headers
• Access-Control-Allow-Methods
• Access-Control-Expose-Headers
• Access-Control-Max-Age

跨源策略

• Cross-Origin-Embedder-Policy
• Cross-Origin-Opener-Policy
• Cross-Origin-Resource-Policy

安全头部

• X-Content-Type-Options
• Permissions-Policy
• Timing-Allow-Origin
• Service-Worker-Allowed

仅用于测试

• Tauri-Custom-Header（不用于生产环境）

在 tauri.conf.json 中配置

在 src-tauri/tauri.conf.json 的 app.security.headers 下配置头部。

值格式

1. 字符串：直接赋值
2. 数组：将各项以逗号连接
3. 对象：键值对格式化为“key value”，并以分号连接
4. Null：忽略该头部

基本配置示例

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Opener-Policy": "same-origin",
        "Cross-Origin-Embedder-Policy": "require-corp",
        "X-Content-Type-Options": "nosniff"
      }
    }
  }
}

完整配置示例

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Opener-Policy": "same-origin",
        "Cross-Origin-Embedder-Policy": "require-corp",
        "Cross-Origin-Resource-Policy": "same-origin",
        "Timing-Allow-Origin": [
          "https://example.com",
          "https://api.example.com"
        ],
        "X-Content-Type-Options": "nosniff",
        "Permissions-Policy": {
          "camera": "()",
          "microphone": "()",
          "geolocation": "(self)"
        },
        "Access-Control-Allow-Methods": ["GET", "POST", "PUT", "DELETE"],
        "Access-Control-Allow-Headers": ["Content-Type", "Authorization"],
        "Access-Control-Max-Age": "86400"
      },
      "csp": "default-src 'self'; connect-src ipc: http://ipc.localhost"
    }
  }
}

启用 SharedArrayBuffer

SharedArrayBuffer 需要特定的跨源策略。请同时配置以下两个头部：

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Opener-Policy": "same-origin",
        "Cross-Origin-Embedder-Policy": "require-corp"
      }
    }
  }
}

CORS 配置示例

限制性 CORS（生产环境推荐）

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Resource-Policy": "same-origin",
        "Access-Control-Allow-Credentials": "false",
        "Access-Control-Allow-Methods": ["GET"],
        "Access-Control-Max-Age": "3600"
      }
    }
  }
}

宽松型 CORS（开发/API 场景）

{
  "app": {
    "security": {
      "headers": {
        "Cross-Origin-Resource-Policy": "cross-origin",
        "Access-Control-Allow-Methods": ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
        "Access-Control-Allow-Headers": ["Content-Type", "Authorization", "X-Requested-With"],
        "Access-Control-Expose-Headers": ["Content-Length", "X-Request-Id"],
        "Access-Control-Max-Age": "86400"
      }
    }
  }
}

开发服务器配置

开发框架需要为其开发服务器单独配置头部。Tauri 注入头部的功能仅适用于生产构建。

Vite（React、Vue、Svelte、Solid、Qwik）

// vite.config.ts
import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
      'X-Content-Type-Options': 'nosniff'
    }
  }
});

Angular

// angular.json
{
  "projects": {
    "your-app": {
      "architect": {
        "serve": {
          "options": {
            "headers": {
              "Cross-Origin-Opener-Policy": "same-origin",
              "Cross-Origin-Embedder-Policy": "require-corp"
            }
          }
        }
      }
    }
  }
}

Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    server: {
      headers: {
        'Cross-Origin-Opener-Policy': 'same-origin',
        'Cross-Origin-Embedder-Policy': 'require-corp'
      }
    }
  }
});

Next.js

// next.config.js
module.exports = {
  async headers() {
    return [
      {
        source: '/(.*)',
        headers: [
          {
            key: 'Cross-Origin-Opener-Policy',
            value: 'same-origin'
          },
          {
            key: 'Cross-Origin-Embedder-Policy',
            value: 'require-corp'
          }
        ]
      }
    ];
  }
};

Trunk（Yew、Leptos）

# Trunk.toml
[serve]
headers = { "Cross-Origin-Opener-Policy" = "same-origin", "Cross-Origin-Embedder-Policy" = "require-corp" }

安全头部参考

Cross-Origin-Opener-Policy（COOP）

控制窗口打开器关系：

值	描述
unsafe-none	默认值，允许访问打开器
same-origin	将浏览上下文限制在同源范围内
same-origin-allow-popups	同源，但允许弹出窗口

Cross-Origin-Embedder-Policy（COEP）

控制资源嵌入：

值	描述
unsafe-none	默认值，无限制
require-corp	要求跨源资源使用 CORP 或 CORS
credentialless	跨源请求不携带凭据

Cross-Origin-Resource-Policy（CORP）

控制谁可以加载你的资源：

值	描述
same-site	仅允许同站点请求
same-origin	仅允许同源请求
cross-origin	允许跨源请求

X-Content-Type-Options

防止 MIME 类型嗅探：

{
  "X-Content-Type-Options": "nosniff"
}

Permissions-Policy

控制浏览器功能访问权限：

{
  "Permissions-Policy": {
    "camera": "()",
    "microphone": "()",
    "geolocation": "(self)",
    "fullscreen": "(self)"
  }
}

最佳实践

1. 同时配置开发环境和生产环境：在框架的开发服务器配置和 tauri.conf.json 中设置头部，以确保行为一致。

2. 使用严格的默认策略：从严格的策略开始，仅在需要时放宽限制。

3. 同时启用 COOP/COEP：要支持 SharedArrayBuffer，必须配置这两个头部。

4. 单独配置 CSP：Content-Security-Policy 应在 app.security.csp 下配置，而不是在 headers 部分配置。

5. 避免在生产环境中使用 Tauri-Custom-Header：此头部仅用于测试。

6. 测试跨源场景：验证 CORS 头部能否与 API 端点正确配合。

故障排查

SharedArrayBuffer 不可用

确保已设置这两个头部：

{
  "Cross-Origin-Opener-Policy": "same-origin",
  "Cross-Origin-Embedder-Policy": "require-corp"
}

开发环境中未应用头部

tauri.conf.json 中的头部仅适用于生产构建。请单独配置开发服务器。

外部 API 的 CORS 错误

为跨域请求添加必需的标头：

{
  "Access-Control-Allow-Methods": ["GET", "POST", "OPTIONS"],
  "Access-Control-Allow-Headers": ["Content-Type", "Authorization"]
}

无法查看自定义标头

通过以下方式公开自定义标头：

{
  "Access-Control-Expose-Headers": ["X-Custom-Header", "X-Request-Id"]
}

版本要求

• HTTP 标头配置需要 Tauri v2.1.0 或更高版本
• 早期版本不支持标头功能

相关配置

• CSP：在 app.security.csp 下配置内容安全策略
• Capabilities：使用 Tauri 的能力系统进行细粒度权限控制
• IPC Security：标头不会影响 IPC 消息处理