Back to Details

configuring-tauri-csp

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Tauri Content Security Policy (CSP) Configuration

Tauri 内容安全策略（CSP）配置

This skill covers Content Security Policy configuration for Tauri v2 desktop applications.
本技能涵盖Tauri v2桌面应用的内容安全策略配置。

Why CSP Matters in Tauri

CSP在Tauri中的重要性

CSP is a security mechanism that mitigates common web vulnerabilities in Tauri applications:
  1. XSS Prevention: Restricts which scripts can execute, blocking injected malicious code
  2. Resource Control: Limits where the WebView can load assets from (scripts, styles, images, fonts)
  3. Trust Boundaries: Strengthens the isolation between frontend WebView and backend Rust code
  4. Attack Surface Reduction: Prevents unauthorized network connections and resource loading
Tauri operates on a trust boundary model where frontend code has limited access to system resources through a well-defined IPC layer. CSP adds an additional layer of protection within the frontend trust zone.
CSP是一种安全机制，可缓解Tauri应用中的常见Web漏洞：
  1. XSS攻击防护：限制可执行的脚本，阻止注入的恶意代码
  2. 资源管控：限制WebView可加载资源的来源（脚本、样式、图片、字体）
  3. 信任边界强化：增强前端WebView与后端Rust代码之间的隔离性
  4. 攻击面缩减：阻止未授权的网络连接和资源加载
Tauri采用信任边界模型，前端代码通过定义明确的IPC层有限地访问系统资源。CSP在前端信任区域内添加了额外的防护层。

How Tauri Implements CSP

Tauri如何实现CSP

Tauri uses a two-part protection strategy:
  1. Local Scripts: Protected through cryptographic hashing at compile time
  2. Styles and External Scripts: Verified using nonces
Tauri automatically appends nonces and hashes to bundled code during compilation. Developers only need to configure application-specific trusted sources.
Important: CSP protection only activates when explicitly configured in the Tauri configuration file.
Tauri采用双重防护策略：
  1. 本地脚本：在编译时通过加密哈希进行保护
  2. 样式与外部脚本：使用随机数（nonce）进行验证
Tauri会在编译期间自动将随机数和哈希附加到打包的代码中。开发者仅需配置应用特定的可信来源。
重要提示：只有在Tauri配置文件中显式配置后，CSP防护才会激活。

Default CSP Behavior

默认CSP行为

By default, Tauri does not apply a CSP. You must explicitly configure it in 
tauri.conf.json
under the 
security
section:
json
{
  "security": {
    "csp": null
  }
}
When 
csp
is 
null
or omitted, no Content Security Policy is enforced.
默认情况下，Tauri不会应用CSP。你必须在
tauri.conf.json
的
security
部分显式配置它：
json
{
  "security": {
    "csp": null
  }
}
当
csp
为
null
或被省略时，不会强制执行任何内容安全策略。

Basic CSP Configuration

基础CSP配置

Minimal Secure Configuration

最小安全配置

json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    }
  }
}
This restricts all resources to the same origin only.
json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    }
  }
}
此配置将所有资源限制为仅同源加载。

Recommended Configuration

推荐配置

json
{
  "security": {
    "csp": {
      "default-src": "'self' customprotocol: asset:",
      "connect-src": "ipc: http://ipc.localhost",
      "font-src": ["https://fonts.gstatic.com"],
      "img-src": "'self' asset: http://asset.localhost blob: data:",
      "style-src": "'unsafe-inline' 'self' https://fonts.googleapis.com"
    }
  }
}
json
{
  "security": {
    "csp": {
      "default-src": "'self' customprotocol: asset:",
      "connect-src": "ipc: http://ipc.localhost",
      "font-src": ["https://fonts.gstatic.com"],
      "img-src": "'self' asset: http://asset.localhost blob: data:",
      "style-src": "'unsafe-inline' 'self' https://fonts.googleapis.com"
    }
  }
}

Common CSP Directives for Tauri

Tauri常用CSP指令

default-src

default-src

Fallback policy for all resource types not explicitly defined.
json
"default-src": "'self' customprotocol: asset:"
Common values:
  • 'self'
    - Same origin only
  • 'none'
    - Block all resources
  • customprotocol:
    - Tauri custom protocol
  • asset:
    - Tauri asset protocol
为所有未明确定义的资源类型提供回退策略。
json
"default-src": "'self' customprotocol: asset:"
常用值：
  • 'self'
    - 仅同源
  • 'none'
    - 阻止所有资源
  • customprotocol:
    - Tauri自定义协议
  • asset:
    - Tauri资源协议

script-src

script-src

Controls which scripts can execute.
json
"script-src": "'self'"
For WebAssembly or Rust-based frontends (Leptos, Yew, Dioxus):
json
"script-src": "'self' 'wasm-unsafe-eval'"
Warning: Never use 
'unsafe-eval'
unless absolutely required.
控制可执行的脚本来源。
json
"script-src": "'self'"
对于WebAssembly或基于Rust的前端框架（Leptos、Yew、Dioxus）：
json
"script-src": "'self' 'wasm-unsafe-eval'"
警告：除非绝对必要，否则绝不要使用
'unsafe-eval'
。

style-src

style-src

Controls stylesheet sources.
json
"style-src": "'self' 'unsafe-inline' https://fonts.googleapis.com"
Note: 
'unsafe-inline'
is often needed for CSS-in-JS libraries but reduces security.
控制样式表来源。
json
"style-src": "'self' 'unsafe-inline' https://fonts.googleapis.com"
注意：
'unsafe-inline'
通常是CSS-in-JS库所需的，但会降低安全性。

connect-src

connect-src

Controls allowed connection destinations for fetch, WebSocket, etc.
json
"connect-src": "ipc: http://ipc.localhost https://api.example.com"
Tauri-specific:
  • ipc:
    - Inter-process communication with Rust backend
  • http://ipc.localhost
    - Alternative IPC endpoint
控制fetch、WebSocket等允许的连接目标。
json
"connect-src": "ipc: http://ipc.localhost https://api.example.com"
Tauri特定值：
  • ipc:
    - 与Rust后端的进程间通信
  • http://ipc.localhost
    - 替代IPC端点

img-src

img-src

Controls image loading sources.
json
"img-src": "'self' asset: http://asset.localhost blob: data:"
Common values:
  • blob:
    - Blob URLs (for dynamically created images)
  • data:
    - Data URLs (base64 encoded images)
  • asset:
    - Tauri asset protocol
控制图片加载来源。
json
"img-src": "'self' asset: http://asset.localhost blob: data:"
常用值：
  • blob:
    - Blob URL（用于动态创建的图片）
  • data:
    - Data URL（Base64编码的图片）
  • asset:
    - Tauri资源协议

font-src

font-src

Controls font loading sources.
json
"font-src": "'self' https://fonts.gstatic.com"
控制字体加载来源。
json
"font-src": "'self' https://fonts.gstatic.com"

frame-src

frame-src

Controls iframe sources.
json
"frame-src": "'none'"
Recommended to block all frames unless specifically needed.
控制iframe来源。
json
"frame-src": "'none'"
除非特别需要，否则建议阻止所有框架。

object-src

object-src

Controls plugin content (Flash, Java, etc.).
json
"object-src": "'none'"
Always set to 
'none'
for modern applications.
控制插件内容（Flash、Java等）。
json
"object-src": "'none'"
对于现代应用，始终设置为
'none'
。

Configuration Format Options

配置格式选项

Object Format (Recommended)

对象格式（推荐）

json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self' 'wasm-unsafe-eval'",
      "style-src": "'self' 'unsafe-inline'"
    }
  }
}
json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self' 'wasm-unsafe-eval'",
      "style-src": "'self' 'unsafe-inline'"
    }
  }
}

Array Format for Multiple Sources

多来源数组格式

json
{
  "security": {
    "csp": {
      "font-src": ["'self'", "https://fonts.gstatic.com", "https://fonts.googleapis.com"]
    }
  }
}
json
{
  "security": {
    "csp": {
      "font-src": ["'self'", "https://fonts.gstatic.com", "https://fonts.googleapis.com"]
    }
  }
}

String Format

字符串格式

json
{
  "security": {
    "csp": "default-src 'self'; script-src 'self'"
  }
}
json
{
  "security": {
    "csp": "default-src 'self'; script-src 'self'"
  }
}

Framework-Specific Configurations

框架特定配置

React/Vue/Svelte (Standard JS Frameworks)

React/Vue/Svelte（标准JS框架）

json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' data: blob:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}
json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' data: blob:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}

Leptos/Yew/Dioxus (Rust/WASM Frameworks)

Leptos/Yew/Dioxus（Rust/WASM框架）

json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self' 'wasm-unsafe-eval'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' data: blob:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}
json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self' 'wasm-unsafe-eval'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' data: blob:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}

With External APIs

对接外部API

json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost https://api.example.com wss://ws.example.com",
      "img-src": "'self' https://cdn.example.com"
    }
  }
}
json
{
  "security": {
    "csp": {
      "default-src": "'self'",
      "script-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost https://api.example.com wss://ws.example.com",
      "img-src": "'self' https://cdn.example.com"
    }
  }
}

Security Best Practices

安全最佳实践

1. Avoid Remote Scripts

1. 避免远程脚本

Never load scripts from CDNs in production:
json
// AVOID - introduces attack vector
"script-src": "'self' https://cdn.jsdelivr.net"

// PREFERRED - bundle all dependencies
"script-src": "'self'"
生产环境中绝不要从CDN加载脚本：
json
// 避免 - 引入攻击向量
"script-src": "'self' https://cdn.jsdelivr.net"

// 推荐 - 打包所有依赖
"script-src": "'self'"

2. Minimize unsafe-inline

2. 最小化unsafe-inline使用

Only use 
'unsafe-inline'
when required by your framework:
json
// More secure
"style-src": "'self'"

// Less secure but sometimes necessary
"style-src": "'self' 'unsafe-inline'"
仅当框架要求时才使用
'unsafe-inline'
：
json
// 更安全
"style-src": "'self'"

// 安全性较低但有时必要
"style-src": "'self' 'unsafe-inline'"

3. Use Restrictive Defaults

3. 使用限制性默认值

Start restrictive and add permissions as needed:
json
{
  "security": {
    "csp": {
      "default-src": "'none'",
      "script-src": "'self'",
      "style-src": "'self'",
      "img-src": "'self'",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}
从严格配置开始，根据需要添加权限：
json
{
  "security": {
    "csp": {
      "default-src": "'none'",
      "script-src": "'self'",
      "style-src": "'self'",
      "img-src": "'self'",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost"
    }
  }
}

4. Block Dangerous Features

4. 禁用危险特性

Always block unused dangerous features:
json
{
  "security": {
    "csp": {
      "object-src": "'none'",
      "base-uri": "'self'",
      "form-action": "'self'"
    }
  }
}
始终禁用未使用的危险特性：
json
{
  "security": {
    "csp": {
      "object-src": "'none'",
      "base-uri": "'self'",
      "form-action": "'self'"
    }
  }
}

Advanced Configuration

高级配置

Disabling CSP Modifications

禁用CSP自动修改

If you need full control over CSP (not recommended):
json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    },
    "dangerousDisableAssetCspModification": true
  }
}
Warning: This disables Tauri's automatic nonce and hash injection.
如果你需要完全控制CSP（不推荐）：
json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    },
    "dangerousDisableAssetCspModification": true
  }
}
警告：这会禁用Tauri的自动随机数和哈希注入功能。

Freeze Prototype

冻结原型

Additional XSS protection by freezing JavaScript prototypes:
json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    },
    "freezePrototype": true
  }
}
通过冻结JavaScript原型提供额外的XSS防护：
json
{
  "security": {
    "csp": {
      "default-src": "'self'"
    },
    "freezePrototype": true
  }
}

Troubleshooting

故障排除

Resources Blocked by CSP

资源被CSP阻止

Check browser DevTools console for CSP violation messages. They indicate which directive is blocking the resource.
Example error:
Refused to load the script 'https://example.com/script.js' because it violates the following Content Security Policy directive: "script-src 'self'"
Solution: Add the domain to the appropriate directive:
json
"script-src": "'self' https://example.com"
查看浏览器开发者工具控制台中的CSP违规消息，它们会指示哪个指令阻止了资源。
示例错误：
Refused to load the script 'https://example.com/script.js' because it violates the following Content Security Policy directive: "script-src 'self'"
解决方案：将域名添加到相应的指令中：
json
"script-src": "'self' https://example.com"

WebAssembly Not Loading

WebAssembly无法加载

Add 
'wasm-unsafe-eval'
to script-src:
json
"script-src": "'self' 'wasm-unsafe-eval'"
在script-src中添加
'wasm-unsafe-eval'
：
json
"script-src": "'self' 'wasm-unsafe-eval'"

Inline Styles Not Working

内联样式无法生效

For CSS-in-JS libraries, add 
'unsafe-inline'
to style-src:
json
"style-src": "'self' 'unsafe-inline'"
对于CSS-in-JS库，在style-src中添加
'unsafe-inline'
：
json
"style-src": "'self' 'unsafe-inline'"

IPC Not Working

IPC无法工作

Ensure connect-src includes Tauri IPC endpoints:
json
"connect-src": "ipc: http://ipc.localhost"
确保connect-src包含Tauri IPC端点：
json
"connect-src": "ipc: http://ipc.localhost"

Complete Example Configuration

完整配置示例

json
{
  "productName": "my-tauri-app",
  "version": "1.0.0",
  "security": {
    "csp": {
      "default-src": "'self' customprotocol: asset:",
      "script-src": "'self'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' asset: http://asset.localhost blob: data:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost",
      "object-src": "'none'",
      "base-uri": "'self'",
      "form-action": "'self'",
      "frame-ancestors": "'none'"
    },
    "freezePrototype": true
  }
}
json
{
  "productName": "my-tauri-app",
  "version": "1.0.0",
  "security": {
    "csp": {
      "default-src": "'self' customprotocol: asset:",
      "script-src": "'self'",
      "style-src": "'self' 'unsafe-inline'",
      "img-src": "'self' asset: http://asset.localhost blob: data:",
      "font-src": "'self'",
      "connect-src": "ipc: http://ipc.localhost",
      "object-src": "'none'",
      "base-uri": "'self'",
      "form-action": "'self'",
      "frame-ancestors": "'none'"
    },
    "freezePrototype": true
  }
}

References

参考资料