必须配置 nelmiocorsbundle 并正确设置 allow_origin、allow_methods 等规则，确保 paths 匹配实际 api 路径，且 credentials 与通配符 origin 不共存；验证需检查 options 响应头并清除生产缓存。
前端 Vue 或 React 应用部署在 localhost:3000，后端 Symfony 接口跑在 localhost:8000，发起请求时浏览器直接拦截并报错“CORS header ‘Access-Control-Allow-Origin’ missing”，必须让 Symfony 正确响应 OPTIONS 预检并返回合法的跨域头。
安装并启用 NelmioCorsBundle
执行 composer require nelmio/cors-bundle 安装依赖包。
确认 config/bundles.php 中已自动注册该 Bundle；若未出现，手动添加 Nelmio\CorsBundle\NelmioCorsBundle::class => ['all' => true]。
创建空配置文件 config/packages/nelmio_cors.yaml，内容留空即可完成基础接入——此时 Bundle 已加载，但尚无规则生效。
写入最小可用 CORS 规则
在 config/packages/nelmio_cors.yaml 中填入以下内容：
nelmio_cors: defaults: allow_origin: ['http://localhost:3000'] allow_methods: ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS'] allow_headers: ['Content-Type', 'X-Requested-With', 'Authorization'] expose_headers: ['Link'] max_age: 3600 origin_regex: false paths: '^/api/': ~
【paths 必须匹配真实请求路径】 比如前端调的是 /v1/users，而这里只写了 ^/api/，那整个规则就完全不触发——务必核对 API 前缀是否一致。
这一步操作起来很简单，直接把上面 YAML 复制粘贴进去就行，注意缩进必须是空格，不能用 Tab。
处理带凭证（credentials）的跨域请求
方法一：允许携带 Cookie 或 Authorization Header
将 allow_origin 改为具体域名列表，例如：['http://localhost:3000', 'https://app.example.com']。
同时设置 allow_credentials: true，并确保 origin_regex: false（正则匹配与 credentials 不兼容）。
方法二：禁用 credentials（临时调试用）
前端 Axios 或 fetch 中移除 credentials: 'include' 或 withCredentials: true，后端配置可继续用 allow_origin: ['*']。
【allow_origin: ['*'] 与 allow_credentials: true 绝对不可共存】 浏览器会直接丢弃响应，控制台报错明确提示 “The value of the 'Access-Control-Allow-Origin' header must not be the wildcard '*'”。
验证与调试 OPTIONS 请求
第一步：打开浏览器开发者工具 → Network 标签页 → 刷新页面 → 找到第一个状态码为 204 或 200 的 OPTIONS 请求。
第二步：点击该请求 → 查看 Response Headers → 确认存在 Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers 三项。
第三步：若缺失或值错误，检查是否清除了生产环境缓存——运行 php bin/console cache:clear --env=prod，否则旧配置仍在生效。
第四步：在 CorsListener::onKernelRequest 中临时加一句 dump('cors hit');，确认请求是否真正进入 Symfony CORS 处理流程；若没输出，说明 Nginx/Apache 拦截了 OPTIONS，根本没到 PHP 层。
