跳转到主要内容
服务器配置

如何在 Nginx 和 Apache 中为 M3U8 配置 CORS

跨源资源共享(CORS)错误是网页浏览器中 HLS 播放失败最常见的原因。本指南提供适用于 Nginx 和 Apache 的专业配置,帮助你正确提供 M3U8 清单、TS/fMP4 分片和 WebVTT 字幕。

当你尝试在网页浏览器中播放 M3U8 流(使用 hls.js、Video.js 等库或原生 HTML5 视频)时,播放器会执行异步 HTTP 请求(XHR 或 Fetch API)来获取清单和媒体分片。如果视频文件所在的域名、子域名或端口与播放器网页不同,浏览器的安全模型便要求请求必须通过跨源资源共享(CORS)检查。

了解 HLS 中的 CORS 问题

如果缺少正确的 CORS 响应头,浏览器会阻止 JavaScript 播放器读取 M3U8 文件内容。你也许能把网址直接粘贴到地址栏中下载文件,但网页播放器会失败,并在控制台显示一条典型错误:

从来源“https://www.yoursite.com”访问“https://cdn.example.com/stream.m3u8”的 XMLHttpRequest 已被 CORS 策略阻止:请求的资源上没有“Access-Control-Allow-Origin”响应头。

要解决这一问题,流媒体服务器或 CDN 必须返回特定的 HTTP 响应头,明确允许播放器所在域名读取这些文件。

必需的 CORS 响应头

为保证顺畅播放,服务器在提供 `.m3u8`、`.ts`、`.mp4`、`.m4s`、`.vtt` 和 `.key` 文件时需要返回以下响应头:

  • Access-Control-Allow-Origin:指定哪些域名可以访问资源。公共流可使用 *,私有流则应指定准确的来源(例如 https://www.yoursite.com)。
  • Access-Control-Allow-Methods:指定允许的 HTTP 方法(例如 GET, HEAD, OPTIONS)。
  • Access-Control-Allow-Headers:指定允许的请求头。HLS 播放器经常会发送自定义请求头,或 Range、Accept 等标准请求头。
  • Access-Control-Expose-Headers:可选但建议设置,用于允许播放器读取 Content-Length 或 Date 等特定响应头。

面向 HLS 的 Nginx 配置

Nginx 广泛用作视频分发的边缘服务器或缓存层。下面是一段专门用于提供 HLS 内容的稳健配置,可放在 server 或 location 配置块内。

location /hls/ {
    # Define the directory where your media files live
    alias /var/www/hls/;
    
    # Optional: Enable byte-range requests for seeking
    add_header Accept-Ranges bytes;

    # CORS configuration
    if ($request_method = 'OPTIONS') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS';
        # Allow the 'Range' header, crucial for HLS segment fetching
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        # Max cache time for the preflight request (20 days)
        add_header 'Access-Control-Max-Age' 1728000;
        add_header 'Content-Type' 'text/plain; charset=utf-8';
        add_header 'Content-Length' 0;
        return 204;
    }
    
    if ($request_method = 'GET') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
    }
    
    if ($request_method = 'HEAD') {
        add_header 'Access-Control-Allow-Origin' '*';
        add_header 'Access-Control-Allow-Methods' 'GET, HEAD, OPTIONS';
        add_header 'Access-Control-Allow-Headers' 'DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range';
        add_header 'Access-Control-Expose-Headers' 'Content-Length,Content-Range';
    }
}

Nginx 预检请求(OPTIONS)

涉及自定义请求头时,浏览器通常会先发送 HTTP OPTIONS 预检请求,再发送实际的 GET 请求。这段 Nginx 配置会立即返回带有允许的 CORS 约束的 HTTP 204 响应,从而明确处理预检请求。

面向 HLS 的 Apache 配置

对于 Apache Web 服务器,可以通过 .htaccess 文件或直接在虚拟主机配置中设置 CORS 响应头。必须确保已经启用 mod_headers(a2enmod headers)。

将以下指令加入配置:

<IfModule mod_headers.c>
    <FilesMatch "\.(m3u8|ts|mp4|m4s|vtt|key)$">
        # Enable CORS for public access
        Header set Access-Control-Allow-Origin "*"
        
        # Define allowed methods
        Header set Access-Control-Allow-Methods "GET, HEAD, OPTIONS"
        
        # Define allowed headers (Crucial for HLS players)
        Header set Access-Control-Allow-Headers "DNT,User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type,Range"
        
        # Expose specific headers to the Javascript client
        Header set Access-Control-Expose-Headers "Content-Length,Content-Range"
    </FilesMatch>
</IfModule>

这段 Apache 配置使用 FilesMatch,只匹配与 HLS 相关的特定文件扩展名,避免把 CORS 策略不必要地应用到 HTML 或 PHP 文件等无关资源上。

排查常见 CORS 问题

1.“存在多个 Access-Control-Allow-Origin 值”错误

如果错误提示响应中包含多个 Access-Control-Allow-Origin 值,说明响应头被添加了两次。常见原因是同时在应用层(例如 Node.js 或 PHP)和 Web 服务器层(Nginx/Apache)配置了 CORS,或者所用 CDN(如 Cloudflare 或 CloudFront)也追加了 CORS 响应头。请确保只有一层负责注入这些响应头。

2. 未处理 OPTIONS 请求

如果 HLS 流需要身份验证(例如通过 Authorization: Bearer ... 自定义请求头传递令牌),浏览器会触发预检 OPTIONS 请求。如果服务器拒绝 OPTIONS 请求(例如返回 401 未授权或 403 禁止访问),后续的 GET 请求就不会执行。请确保服务器明确处理并允许无需身份验证的 OPTIONS 请求。

3. 缓存了过期的 CORS 响应头

更新 Nginx 或 Apache 配置后,中间缓存或 CDN 可能仍保留原先有问题的响应。每次修改 CORS 配置后,都应清除 CDN 缓存,并绕过浏览器本地缓存(使用无痕模式,或在开发者工具中禁用缓存)。

验证配置

应用配置后,可以在命令行中使用 curl 进行验证:

curl -I -H "Origin: https://freem3u8.com" https://your-server.com/hls/stream.m3u8

检查响应头中是否存在 Access-Control-Allow-Origin: *。如果存在,说明服务器配置正确,流媒体内容应能在浏览器播放器中顺畅播放。