React/Vite/Capacitor iOS应用中如何为媒体请求添加Referer头

核心原因 #

iOS端Capacitor基于WKWebView实现，它在加载跨域媒体资源时默认不会自动发送Referer头；同时img/video这类原生媒体标签的加载不受XMLHttpRequest/Fetch控制，直接通过JS手动添加请求头的方式本身就不生效。

解决方案 #

方案1：修改Capacitor的WKWebView配置强制发送Referer #

直接在iOS项目层面配置WKWebView，开启Referer自动发送：

1. 打开iOS项目的AppDelegate.swift文件
2. 在application(_:didFinishLaunchingWithOptions:)方法中添加以下配置：

import WebKit

func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
    // 保留原有代码...
    
    let webConfig = WKWebViewConfiguration()
    // 配置Referer发送策略
    let webpagePrefs = WKWebpagePreferences()
    webpagePrefs.allowsContentJavaScript = true
    webConfig.defaultWebpagePreferences = webpagePrefs
    // 替换Capacitor默认的WebView配置
    CapacitorBridge.defaultWebViewConfiguration = webConfig
    
    return true
}

3. 同时在Info.plist中补充跨域配置：
   添加NSAppTransportSecurity字典，若CloudFront为HTTPS，推荐配置NSExceptionDomains指定目标域名并开启NSIncludesSubdomains、NSExceptionAllowsInsecureHTTPLoads（按需）；再添加NSReferrerPolicy字段，值设为origin-when-cross-origin。

方案2：通过Fetch预加载媒体转Blob URL使用 #

绕过原生媒体标签的限制，先通过Fetch手动携带Referer获取资源，转成Blob URL后再赋值给媒体标签：

import { useState, useEffect } from 'react';

const MediaLoader = ({ mediaUrl }) => {
    const [blobSrc, setBlobSrc] = useState(null);

    useEffect(() => {
        let blobUrl = null;
        const loadMedia = async () => {
            try {
                const res = await fetch(mediaUrl, {
                    headers: {
                        'Referer': window.location.origin // 替换为你的合法Referer值
                    }
                });
                const blob = await res.blob();
                blobUrl = URL.createObjectURL(blob);
                setBlobSrc(blobUrl);
            } catch (err) {
                console.error('媒体加载失败:', err);
            }
        };

        loadMedia();
        // 组件卸载时释放Blob URL，避免内存泄漏
        return () => blobUrl && URL.revokeObjectURL(blobUrl);
    }, [mediaUrl]);

    if (!blobSrc) return <div>加载中...</div>;

    return mediaUrl.match(/\.(mp4|mov)$/) ? (
        <video controls src={blobSrc} />
    ) : (
        <img src={blobSrc} alt="媒体资源" />
    );
};

export default MediaLoader;

注意：大文件资源会占用客户端内存，务必在组件卸载时释放Blob URL。

方案3：调整CloudFront验证规则（替代方案） #

如果客户端方案难以落地，可以从服务端调整：

• 改用CloudFront签名URL：通过签名参数验证请求合法性，完全不依赖Referer头，安全性更高，还能绕过各平台的Referer差异问题。
• 放宽Referer验证规则：比如结合Capacitor应用的固定User-Agent格式，同时允许合法的空Referer场景（需评估安全风险）。

测试注意事项 #

• 必须用iOS真机测试，模拟器的WKWebView行为与真机存在差异
• 若使用@capacitor/filesystem插件，也可先将媒体下载到本地再加载，无需依赖Referer头

内容的提问来源于stack exchange，提问作者tosh