Настройка CORS-заголовков на сайте: полное руководство 2026

CORS — это одна из тех тем, где разработчики чаще всего теряют несколько часов жизни, глядя в консоль браузера и видя красную строчку с текстом "has been blocked by CORS policy". Я через это прошёл десятки раз, и сейчас расскажу всё, что знаю о настройке CORS-заголовков правильно — на Nginx, Apache, PHP и в облачных конфигурациях.

Что такое CORS и почему это вообще важно

CORS расшифровывается как Cross-Origin Resource Sharing — механизм, который позволяет или запрещает браузеру делать запросы к ресурсам с другого домена, протокола или порта. Придумали это не для того, чтобы усложнить жизнь разработчикам, а чтобы защитить пользователей от атак типа CSRF, когда вредоносный сайт пытается от имени пользователя стянуть данные с другого ресурса.

Грубо говоря, браузер работает по принципу Same-Origin Policy: скрипт с домена example.com не может просто так сделать fetch-запрос к api.otherdomain.com. Сервер должен явно разрешить это через специальные HTTP-заголовки. Если заголовков нет — браузер блокирует ответ, даже если сервер вернул 200 OK. Именно поэтому столько путаницы: сервер отвечает нормально, но браузер всё равно выдаёт ошибку.

Я помню случай с одним клиентом — интернет-магазин на Bitrix, который хотел подключить стороннее мобильное приложение на React Native к своему API. Мы потратили полдня, пока не поняли, что проблема не в коде приложения и не в логике API — просто на сервере не было ни одного CORS-заголовка. Сервер крутился на Nginx, и стоило добавить буквально 5 строк конфига — всё заработало. Но эти 5 строк надо знать правильно, иначе либо сломаешь безопасность, либо ничего не заработает.

Если ты работаешь с API-интеграциями — обязательно прочитай пошаговое руководство по настройке API интеграций, там много пересекающихся тем.

Как работает CORS: предварительные запросы и preflight

Прежде чем лезть в конфиги, нужно понять механизм. CORS-запросы делятся на два типа: простые (simple requests) и сложные, которые требуют предварительного запроса — preflight.

Простые запросы — это GET, POST с Content-Type: application/x-www-form-urlencoded, multipart/form-data или text/plain. Браузер отправляет их сразу, без предварительной проверки, и просто смотрит на заголовки ответа. Если сервер вернул нужный Access-Control-Allow-Origin — всё хорошо.

Сложные запросы — это всё остальное: PUT, DELETE, PATCH, POST с JSON-телом, запросы с кастомными заголовками (например, Authorization). Перед таким запросом браузер автоматически отправляет OPTIONS-запрос на тот же URL — это и есть preflight. Сервер должен ответить на этот OPTIONS-запрос с нужными CORS-заголовками и статусом 200 или 204. Только после этого браузер отправит реальный запрос.

На практике это значит, что если у тебя REST API с JSON и токеном авторизации — у тебя сложные запросы, и ты обязан обработать OPTIONS. Многие забывают про это, настраивают заголовки только для GET/POST, а потом удивляются, почему preflight возвращает 405 Method Not Allowed.

Настройка CORS на Nginx

Nginx — мой основной инструмент для настройки CORS на продакшн-серверах. Конфигурация получается чистой, не зависит от кода приложения и применяется сразу ко всем запросам. Вот базовый блок, который я использую для большинства проектов:

server {
    listen 443 ssl;
    server_name api.example.com;

    # Список разрешённых origins
    set $cors_origin "";
    if ($http_origin ~* "^https://(www\.)?example\.com$") {
        set $cors_origin $http_origin;
    }
    if ($http_origin ~* "^https://app\.example\.com$") {
        set $cors_origin $http_origin;
    }

    location / {
        # Устанавливаем заголовки для всех запросов
        add_header 'Access-Control-Allow-Origin' $cors_origin always;
        add_header 'Access-Control-Allow-Credentials' 'true' always;
        add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, PATCH, OPTIONS' always;
        add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Accept, X-Requested-With, Cache-Control' always;
        add_header 'Access-Control-Max-Age' '86400' always;

        # Обработка preflight-запросов
        if ($request_method = 'OPTIONS') {
            add_header 'Access-Control-Allow-Origin' $cors_origin always;
            add_header 'Access-Control-Allow-Credentials' 'true' always;
            add_header 'Access-Control-Allow-Methods' 'GET, POST, PUT, DELETE, PATCH, OPTIONS' always;
            add_header 'Access-Control-Allow-Headers' 'Authorization, Content-Type, Accept, X-Requested-With, Cache-Control' always;
            add_header 'Access-Control-Max-Age' '86400' always;
            add_header 'Content-Length' '0';
            add_header 'Content-Type' 'text/plain; charset=utf-8';
            return 204;
        }

        proxy_pass http://127.0.0.1:9000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Несколько важных моментов в этой конфигурации. Во-первых, я использую динамический $cors_origin вместо жёсткого *. Это принципиально, если ты используешь Access-Control-Allow-Credentials: true — с wildcard * и credentials браузер откажет. Во-вторых, директива always в add_header означает, что заголовок будет добавлен даже при ошибочных статусах (4xx, 5xx) — без неё браузер не увидит CORS-заголовков при ошибках и покажет неправильное сообщение.

В-третьих, Access-Control-Max-Age: 86400 — это кеш preflight-ответа на 24 часа. Без него браузер будет слать OPTIONS перед каждым запросом. На активно используемом API это лишняя нагрузка.

Одна тонкость с Nginx: директивы add_header внутри блока if перекрывают родительские add_header. Поэтому в примере выше заголовки продублированы и в основном блоке, и внутри if ($request_method = 'OPTIONS'). Да, это некрасиво, но это особенность Nginx. Альтернатива — использовать map и include, но для большинства проектов дублирование проще.

Настройка CORS на Apache и .htaccess

Если у тебя Apache или хостинг, где нет доступа к конфигу Nginx — настраиваем через .htaccess. Это чуть менее гибко, но вполне рабочий вариант. На WordPress-сайтах я обычно делаю так:

# Включаем модуль headers
Header always set Vary "Origin"

# Разрешаем конкретные origins
SetEnvIf Origin "^https://(www\.)?example\.com$" CORS_ALLOWED_ORIGIN=$0
SetEnvIf Origin "^https://app\.example\.com$" CORS_ALLOWED_ORIGIN=$0

Header always set Access-Control-Allow-Origin "%{CORS_ALLOWED_ORIGIN}e" env=CORS_ALLOWED_ORIGIN
Header always set Access-Control-Allow-Credentials "true" env=CORS_ALLOWED_ORIGIN
Header always set Access-Control-Allow-Methods "GET, POST, PUT, DELETE, PATCH, OPTIONS" env=CORS_ALLOWED_ORIGIN
Header always set Access-Control-Allow-Headers "Authorization, Content-Type, Accept, X-Requested-With" env=CORS_ALLOWED_ORIGIN
Header always set Access-Control-Max-Age "86400" env=CORS_ALLOWED_ORIGIN

# Обработка preflight
RewriteEngine On
RewriteCond %{REQUEST_METHOD} OPTIONS
RewriteRule ^(.*)$ $1 [R=204,L]

Важно: для работы этого конфига нужны включённые модули mod_headers и mod_rewrite. На большинстве хостингов они есть по умолчанию. Если нет — обратись к хостеру или используй PHP-решение ниже.

Заголовок Vary: Origin здесь не случаен. Он говорит кешам (CDN, прокси) что ответ может различаться в зависимости от Origin. Без него CDN может закешировать ответ для одного origin и отдать его другому — тогда CORS перестанет работать. Если у тебя настроен CDN, рекомендую посмотреть руководство по настройке CDN — там эта тема тоже затрагивается.

CORS на уровне PHP: Laravel, WordPress, Bitrix

Иногда настраивать CORS на уровне веб-сервера неудобно или невозможно. Тогда делаем это в коде. Вот как я решаю это в разных стеках.

Laravel

В Laravel начиная с версии 7+ есть встроенный пакет fruitcake/laravel-cors, который сейчас называется laravel/sanctum для API или просто middleware. Настройка через config/cors.php:

 ['api/*', 'sanctum/csrf-cookie'],
    'allowed_methods' => ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
    'allowed_origins' => [
        'https://example.com',
        'https://app.example.com',
    ],
    'allowed_origins_patterns' => [
        // Можно использовать regex: '/^https:\/\/.*\.example\.com$/'
    ],
    'allowed_headers' => [
        'Content-Type',
        'Authorization',
        'X-Requested-With',
        'Accept',
        'Origin',
    ],
    'exposed_headers' => ['X-Total-Count', 'X-Page'],
    'max_age' => 86400,
    'supports_credentials' => true,
];

Убедись, что middleware \Fruitcake\Cors\HandleCors::class (или \Illuminate\Http\Middleware\HandleCors::class в Laravel 10+) стоит первым в глобальном middleware-стеке в app/Http/Kernel.php. Если поставить его после других middleware — могут быть проблемы с preflight.

WordPress

В WordPress CORS удобнее всего настраивать через functions.php или отдельный плагин. Я обычно добавляю это в functions.php темы или в MU-плагин:

log_format cors_debug '$remote_addr - $http_origin - $request - $status - $sent_http_access_control_allow_origin';
access_log /var/log/nginx/cors_debug.log cors_debug;

const io = require('socket.io')(server, {
    cors: {
        origin: ['https://example.com', 'https://app.example.com'],
        methods: ['GET', 'POST'],
        credentials: true
    }
});