Express CORS 에러 해결 (cors 패키지 사용과 미사용)

CORS 에러("No 'Access-Control-Allow-Origin' header is present")는 http://localhost:5173 같은 한 출처의 웹 페이지가 다른 출처의 API를 호출했는데, 응답이 그 출처를 허용한다고 말하지 않아서 브라우저가 페이지가 응답을 읽지 못하게 막았다는 뜻입니다. 해결은 서버에서 합니다. 페이지의 출처를 담은 Access-Control-Allow-Origin을 보내고, 브라우저의 프리플라이트 OPTIONS 요청에는 받아들일 메서드와 헤더로 응답하세요. Express에서는 미들웨어 몇 줄이나 cors 패키지의 app.use(cors())면 됩니다.

const express = require('express');
const app = express();

const ALLOWED_ORIGIN = 'https://app.example.com';

function cors(req, res, next) {
    res.set('Access-Control-Allow-Origin', ALLOWED_ORIGIN);
    res.set('Vary', 'Origin');
    if (req.method === 'OPTIONS') {
        res.set('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE');
        res.set('Access-Control-Allow-Headers', 'Content-Type, Authorization');
        res.set('Access-Control-Max-Age', '600');
        return res.sendStatus(204);
    }
    next();
}

app.use(cors);

app.get('/api/products', (req, res) => {
    res.json([{ id: 1, name: 'Lamp' }]);
});

app.put('/api/products/:id', (req, res) => {
    res.json({ updated: req.params.id });
});

// GET /api/products
app.listen(3000);

응답은 상품 목록이고, Headers 탭에 access-control-allow-origin: https://app.example.com이 보입니다. 그 출처의 페이지는 응답을 읽어도 된다는 뜻입니다. 이제 Origin: https://app.example.com과 Access-Control-Request-Method: PUT 헤더를 붙여 OPTIONS /api/products/1을 보내 보세요. 브라우저가 PUT 전에 보내는 프리플라이트이고, 응답은 허용된 메서드와 헤더를 담은, 본문 없는 204입니다.

브라우저가 확인하는 것

같은 출처의 페이지는 아무것도 필요 없습니다. 교차 출처 요청에서 브라우저는 다음 응답 헤더를 읽습니다.

단순한 GET이나 폼 형식의 POST는 서버로 바로 가고, 브라우저는 응답의 Access-Control-Allow-Origin을 확인합니다. 서버는 어쨌든 요청을 실행합니다. CORS는 페이지가 결과를 볼 수 있는지만 정합니다. JSON 본문, Authorization 헤더, PUT이나 DELETE 같은 메서드가 있는 요청 앞에는 프리플라이트 OPTIONS 요청이 가고, 프리플라이트 응답이 허용할 때만 실제 요청이 전송됩니다. 그래서 CORS 미들웨어는 어떤 라우트나 인증 검사보다 먼저 OPTIONS에 응답해야 합니다.

여러 출처를 쿠키와 함께 허용하기

Access-Control-Allow-Origin에는 출처 하나나 *만 들어가고 목록은 안 됩니다. 여러 개를 허용하려면 요청의 Origin 헤더를 허용 목록과 비교해서, 일치하면 그대로 돌려주세요.

const express = require('express');
const app = express();

const allowed = new Set(['https://app.example.com', 'http://localhost:5173']);

app.use((req, res, next) => {
    const origin = req.get('origin');
    if (origin && allowed.has(origin)) {
        res.set('Access-Control-Allow-Origin', origin);
        res.set('Access-Control-Allow-Credentials', 'true');
    }
    res.set('Vary', 'Origin');
    if (req.method === 'OPTIONS') {
        res.set('Access-Control-Allow-Methods', 'GET, POST');
        res.set('Access-Control-Allow-Headers', 'Content-Type');
        return res.sendStatus(204);
    }
    next();
});

app.get('/api/me', (req, res) => {
    res.json({ origin: req.get('origin') ?? null });
});

app.listen(3000);

첫 요청에는 curl이나 같은 출처 페이지에서의 호출처럼 Origin 헤더가 없어서, {"origin":null}을 받고 CORS 헤더는 붙지 않습니다. Origin: http://localhost:5173 헤더를 붙여 GET /api/me를 보내면, Headers 탭에 그 출처가 그대로 돌아온 것과 access-control-allow-credentials: true가 보입니다. 헤더를 Origin: https://evil.example로 바꾸면 두 CORS 헤더가 모두 사라집니다. 서버는 여전히 응답하지만, 브라우저라면 페이지가 그것을 읽지 못하게 막습니다. Access-Control-Allow-Credentials: true는 페이지가 쿠키를 보낼 수 있게 하는데(fetch(url, { credentials: 'include' })로), 브라우저는 이것과 *의 조합을 거부하므로 쿠키를 쓰려면 항상 정확한 출처가 필요합니다.

cors 패키지

cors 패키지는 같은 일을 옵션으로 합니다. npm install cors로 설치하세요.

const cors = require('cors');

// Any origin, no cookies: fine for a public read-only API.
app.use(cors());

// Only your frontend, with cookies.
app.use(cors({
    origin: ['https://app.example.com', 'http://localhost:5173'],
    credentials: true,
    methods: ['GET', 'POST', 'PUT', 'DELETE'],
}));

// One route only.
app.get('/api/public', cors(), handler);

옵션 없이 호출하면 cors()는 Access-Control-Allow-Origin: *을 보내고 모든 프리플라이트에 응답합니다. *는 로그인이 필요 없는 공개 데이터에만 쓰세요.

흔한 실수

라우트나 인증 미들웨어 뒤에 CORS를 추가하는 것. 프리플라이트 OPTIONS 요청에는 Authorization 헤더가 없어서, 먼저 놓인 인증 검사가 401로 응답하고 브라우저는 CORS 에러를 보고합니다. CORS 미들웨어를 먼저 등록하세요.

쿠키와 함께 *를 설정하는 것. 브라우저가 응답을 거부합니다. 대신 특정 출처를 그대로 돌려주세요.

프론트엔드에서 CORS를 고치려는 것. mode: 'no-cors' 같은 요청 옵션은 제한을 풀어 주지 않습니다. 읽을 수 없는 불투명한 응답을 줄 뿐입니다. 서버의 헤더만이 고칠 수 있습니다.

app.use()와 미들웨어 순서의 동작은 Express 미들웨어를 참고하세요.