Webman本身不内置CDN集成，关键在于前端构建时将publicPath设为CDN域名，确保HTML中资源链接全为CDN地址，并避免StaticFile中间件误处理CDN请求，Nginx需放行CDN域名且不覆盖其缓存头。
Webman 本身不内置 CDN 集成，但静态资源走 CDN 的关键不在框架里“配 CDN”，而在于：前端构建时把资源 URL 指向 CDN 域名，后端（Webman）只负责不干扰、不重写、不强制拦截这些路径——尤其是要确保 StaticFile 中间件不误杀 CDN 域名下的请求。
Webpack/Vite 打包时必须改 publicPath
这是最常被跳过的一步。Webman 不参与前端构建，所以它完全不知道你用了 CDN；所有路径替换必须在打包阶段完成。
- Webpack 项目（Vue2/React）：在
vue.config.js或webpack.config.js中设置publicPath: 'https://static.example.com/'（生产环境），不能是/或./ - Vite 项目（Vue3/React）：在
vite.config.ts中配置base: 'https://static.example.com/' - 务必确认构建产物中 HTML 里的
<script src>、<link href>、<img src>全部以https://static.example.com/开头——用grep -r "static.example.com" dist/快速验证
StaticFile 中间件需放行 CDN 域名请求
默认的 app/middleware/StaticFile.php 只处理本域请求（如 /static/logo.png），但如果前端已切到 https://static.example.com/logo.png，那这个请求根本不会进 Webman —— 它由浏览器直连 CDN。真正需要检查的是：有没有人误把 CDN 域名反代回 Webman？或者本地开发时混用域名导致 404？
前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。前端设计与 UI/UX 全方位优化专家。覆盖视觉层次、排版系统、色彩理论、响应式布局、交互体验、动画动效、无障碍访问、性能优化八大维度，帮助开发者将普通页面升级为高品质产品级界面。
- 确认 Nginx/Apache 没有把
static.example.com的请求proxy_pass到 Webman —— CDN 域名必须绕过 Webman，直通边缘节点 - 如果因调试需要本地代理 CDN 域名（不推荐），必须在
StaticFile::process()开头加判断：if ($request->getHeaderLine('host') === 'static.example.com') { return $next($request); }，避免被/.xxx过滤逻辑拦截 - 别在
config/static.php里给 CDN 路径配middleware—— 它只管 Webman 自己 serve 的路径
Nginx 层禁用对 CDN 域名的缓存头覆盖
CDN 节点依赖源站返回的 Cache-Control 和 Expires 头做缓存决策。如果你在 Webman 的 StaticFile 中间件里写了 $response->header('Cache-Control', 'public, max-age=3600')，而该中间件又意外处理了 CDN 请求，就会污染真实缓存策略。
立即学习“前端免费学习笔记（深入）”；
- Webman 应只对
/static/、/assets/等本地路径生效；CDN 域名的响应应由 Nginx 直接返回，或由 CDN 自行控制 - Nginx 配置中，针对 CDN 域名的
server块里，**不要**加add_header Cache-Control—— 让 CDN 自主决定 - 真正要设缓存头的地方是：Webman 服务的静态路径（如
/static/），且应匹配资源类型，例如 JS/CSS 设max-age=31536000，HTML 设no-cache
最容易被忽略的点是：CDN 缓存是否真的命中。打开浏览器开发者工具 → Network → 看某个 JS 文件的 Response Headers 里是否有 X-Cache: HIT from ...（Cloudflare）或 X-Cache: HIT（阿里云）。没有，说明要么 DNS 没切到 CDN，要么源站返回了 Cache-Control: no-store，要么路径被 Webman 中间件劫持了。这三者任何一个出问题，CDN 就形同虚设。
