当你尝试在网页浏览器中播放 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: *。如果存在,说明服务器配置正确,流媒体内容应能在浏览器播放器中顺畅播放。