configuring-tauri-http-headers

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Tauri HTTP Headers Security Configuration

Tauri HTTP头安全配置

This skill covers HTTP headers configuration in Tauri v2.1.0+, enabling developers to set security headers in webview responses.

本指南涵盖Tauri v2.1.0及以上版本中的HTTP头配置，帮助开发者在webview响应中设置安全头。

Overview

概述

Tauri allows configuring HTTP headers that are included in responses to the webview. These headers apply to production builds and do not affect IPC messages or error responses.

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

Supported Headers (Allowlist)

支持的头（允许列表）

Tauri restricts header configuration to a specific allowlist for security:

Tauri将头配置限制在特定的允许列表中以保障安全：

CORS Headers

CORS头

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

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

Cross-Origin Policies

跨源策略

```
Cross-Origin-Embedder-Policy
```
```
Cross-Origin-Opener-Policy
```
```
Cross-Origin-Resource-Policy
```

```
Cross-Origin-Embedder-Policy
```
```
Cross-Origin-Opener-Policy
```
```
Cross-Origin-Resource-Policy
```

Security Headers

安全头

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

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

Testing Only

仅用于测试

```
Tauri-Custom-Header
```
(not for production use)

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

Configuration in tauri.conf.json

在tauri.conf.json中配置

Headers are configured under

app.security.headers

src-tauri/tauri.conf.json

头配置位于

src-tauri/tauri.conf.json

的

app.security.headers

下。

Value Formats

值格式

String: Direct assignment
Array: Items joined by commas
Object: Key-value pairs formatted as "key value", joined by semicolons
Null: Header is ignored

字符串：直接赋值
数组：项之间用逗号连接
对象：键值对格式为"key value"，用分号连接
Null：忽略该头

Basic Configuration Example

基础配置示例

json

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

json

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

Comprehensive Configuration Example

完整配置示例

json

{
  "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"
    }
  }
}

json

{
  "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"
    }
  }
}

Enabling SharedArrayBuffer

启用SharedArrayBuffer

SharedArrayBuffer

requires specific cross-origin policies. Configure both headers together:

json

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

SharedArrayBuffer

需要特定的跨源策略。需同时配置两个头：

json

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

CORS Configuration Examples

CORS配置示例

Restrictive CORS (Recommended for Production)

严格CORS配置（生产环境推荐）

json

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

json

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

Permissive CORS (Development/API Scenarios)

宽松CORS配置（开发/API场景）

json

{
  "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"
      }
    }
  }
}

json

{
  "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"
      }
    }
  }
}

Development Server Configuration

开发服务器配置

Development frameworks require separate header configuration for their dev servers. Tauri header injection only applies to production builds.

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

Vite (React, Vue, Svelte, Solid, Qwik)

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

typescript

// 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'
    }
  }
});

typescript

// 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

json

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

json

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

Nuxt

typescript

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

typescript

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

Next.js

javascript

// 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'
          }
        ]
      }
    ];
  }
};

javascript

// 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（Yew、Leptos）

toml

undefined

toml

undefined

Trunk.toml

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

undefined

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

undefined

Security Headers Reference

安全头参考

Cross-Origin-Opener-Policy (COOP)

Cross-Origin-Opener-Policy（COOP）

Controls window opener relationships:

Value	Description
`unsafe-none`	Default, allows opener access
`same-origin`	Isolates browsing context to same-origin
`same-origin-allow-popups`	Same-origin but allows popups

控制窗口 opener 关系：

值	描述
`unsafe-none`	默认值，允许opener访问
`same-origin`	将浏览上下文隔离到同源
`same-origin-allow-popups`	同源但允许弹出窗口

Cross-Origin-Embedder-Policy (COEP)

Cross-Origin-Embedder-Policy（COEP）

Controls resource embedding:

Value	Description
`unsafe-none`	Default, no restrictions
`require-corp`	Requires CORP or CORS for cross-origin resources
`credentialless`	Cross-origin requests without credentials

控制资源嵌入：

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

Cross-Origin-Resource-Policy (CORP)

Cross-Origin-Resource-Policy（CORP）

Controls who can load your resources:

Value	Description
`same-site`	Only same-site requests
`same-origin`	Only same-origin requests
`cross-origin`	Allows cross-origin requests

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

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

X-Content-Type-Options

Prevents MIME type sniffing:

json

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

防止MIME类型嗅探：

json

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

Permissions-Policy

Controls browser feature access:

json

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

控制浏览器功能访问：

json

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

Best Practices

最佳实践

Configure Both Dev and Prod: Set headers in both your framework's dev server config and
```
tauri.conf.json
```
for consistent behavior.
Use Restrictive Defaults: Start with restrictive policies and loosen only as needed.
Enable COOP/COEP Together: For
```
SharedArrayBuffer
```
support, both headers must be configured.
Separate CSP Configuration: Content-Security-Policy is configured under
```
app.security.csp
```
, not in the headers section.
Avoid Tauri-Custom-Header in Production: This header is for testing purposes only.
Test Cross-Origin Scenarios: Verify that CORS headers work correctly with your API endpoints.

同时配置开发和生产环境：在框架的开发服务器配置和
```
tauri.conf.json
```
中都设置头，以保证行为一致。
使用严格的默认值：从严格的策略开始，仅在需要时放宽。
同时启用COOP/COEP：要支持
```
SharedArrayBuffer
```
，必须同时配置这两个头。
单独配置CSP：内容安全策略（CSP）需在
```
app.security.csp
```
下配置，而非头部分。
生产环境避免使用Tauri-Custom-Header：该头仅用于测试目的。
测试跨源场景：验证CORS头与你的API端点是否能正常工作。

Troubleshooting

故障排除

SharedArrayBuffer Not Available

SharedArrayBuffer不可用

Ensure both headers are set:

json

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

确保同时设置两个头：

json

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

Headers Not Applied in Development

开发环境中头未生效

Headers in

tauri.conf.json

only apply to production builds. Configure your dev server separately.

tauri.conf.json

中的头仅适用于生产构建。需单独配置开发服务器。

CORS Errors with External APIs

与外部API交互时出现CORS错误

Add required headers for cross-origin requests:

json

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

添加跨源请求所需的头：

json

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

Custom Headers Not Visible

自定义头不可见

Expose custom headers via:

json

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

通过以下方式暴露自定义头：

json

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

configuring-tauri-http-headers

Original

Translation

Tauri HTTP Headers Security Configuration

Tauri HTTP头安全配置

Overview

概述

Supported Headers (Allowlist)

支持的头（允许列表）

CORS Headers

CORS头

Cross-Origin Policies

跨源策略

Security Headers

安全头

Testing Only

仅用于测试

Configuration in tauri.conf.json

在tauri.conf.json中配置

Value Formats

值格式

Basic Configuration Example

基础配置示例

Comprehensive Configuration Example

完整配置示例

Enabling SharedArrayBuffer

启用SharedArrayBuffer

CORS Configuration Examples

CORS配置示例

Restrictive CORS (Recommended for Production)

严格CORS配置（生产环境推荐）

Permissive CORS (Development/API Scenarios)

宽松CORS配置（开发/API场景）

Development Server Configuration

开发服务器配置

Vite (React, Vue, Svelte, Solid, Qwik)

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

Angular

Angular

Nuxt

Nuxt

Next.js

Next.js

Trunk (Yew, Leptos)

Trunk（Yew、Leptos）

Trunk.toml

Trunk.toml

Security Headers Reference

安全头参考

Cross-Origin-Opener-Policy (COOP)

Cross-Origin-Opener-Policy（COOP）

Cross-Origin-Embedder-Policy (COEP)

Cross-Origin-Embedder-Policy（COEP）

Cross-Origin-Resource-Policy (CORP)

Cross-Origin-Resource-Policy（CORP）

X-Content-Type-Options

X-Content-Type-Options

Permissions-Policy

Permissions-Policy

Best Practices

最佳实践

Troubleshooting

故障排除

SharedArrayBuffer Not Available

SharedArrayBuffer不可用

Headers Not Applied in Development

开发环境中头未生效

CORS Errors with External APIs

与外部API交互时出现CORS错误

Custom Headers Not Visible

自定义头不可见

Version Requirements

版本要求

Related Configuration

相关配置