Node.js에서 CORS 에러 발생 원인과 해결 방법

Node.js에서 CORS 에러 발생 원인과 해결 방법

프론트엔드와 백엔드가 분리된 구조에서 웹 개발을 하다 보면 흔히 마주치는 문제가 바로 CORS(Cross-Origin Resource Sharing) 에러입니다. 특히 Node.js를 백엔드로 사용할 때, 이 오류는 초보 개발자뿐만 아니라 실무에서도 빈번히 발생하는 문제 중 하나입니다.

📌 목차

• CORS란 무엇인가요?
• Node.js에서 CORS 에러가 발생하는 이유
• CORS 문제 해결 방법
• 최신 사례와 실전 대응 전략

CORS란 무엇인가요?

CORS는 웹 브라우저에서 보안을 위해 적용하는 정책으로, 다른 출처(origin)의 리소스를 요청할 때 제한을 거는 방식입니다. 예를 들어, http://localhost:3000에서 실행되는 프론트엔드가 http://localhost:4000의 API를 호출하려고 하면 브라우저는 이를 '다른 출처'로 간주하고 CORS 정책에 따라 요청을 차단할 수 있어요.

Node.js에서 CORS 에러가 발생하는 이유

Node.js 서버는 기본적으로 모든 도메인에서의 요청을 허용하지 않습니다. 따라서 다른 도메인, 포트, 혹은 프로토콜에서 들어오는 요청은 CORS 정책에 의해 차단될 수 있습니다.

예를 들어, 프론트엔드가 http://localhost:3000에서 실행되고 있고, 백엔드가 http://localhost:5000에 존재한다면, 이 두 주소는 서로 다른 Origin으로 인식되어 CORS 오류가 발생할 수 있어요.

기본적인 오류 메시지 예시:

Access to fetch at 'http://localhost:5000/api/data' from origin 'http://localhost:3000' has been blocked by CORS policy:
No 'Access-Control-Allow-Origin' header is present on the requested resource.
    

이는 서버에서 클라이언트 요청을 허용하도록 명시하지 않았기 때문에 발생하는 문제입니다.

CORS 문제 해결 방법

Node.js 환경에서는 cors 미들웨어를 사용하면 손쉽게 이 문제를 해결할 수 있어요. 다음은 Express.js 환경에서 CORS를 허용하는 기본적인 방법입니다.

npm install cors

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

app.use(cors()); // 모든 도메인 허용

app.get('/api/data', (req, res) => {
    res.json({ message: 'CORS 허용 완료!' });
});

app.listen(5000, () => {
    console.log('서버 실행 중: http://localhost:5000');
});
    

위 코드에서 app.use(cors()) 한 줄만 추가해도 기본적인 CORS 문제는 대부분 해결됩니다. 하지만, 보안상 이유로 특정 도메인만 허용하고 싶은 경우, 아래와 같이 옵션을 지정할 수도 있어요.

app.use(cors({
    origin: 'http://localhost:3000',
    credentials: true
}));
    

최신 사례와 실전 대응 전략

최근에는 다양한 클라우드 환경이나 SaaS 플랫폼에서도 Node.js 서버를 운영하며 CORS 문제를 겪는 경우가 많아졌습니다. 특히 Vercel, Netlify, AWS Lambda와 같은 플랫폼에서 서버리스 형태로 API를 제공할 경우에도 CORS 설정은 필수입니다.

이러한 환경에서는 보통 serverless.yml 파일이나 플랫폼의 설정에서 CORS를 명시해야 하며, 경우에 따라 미리 CORS 프리플라이트(preflight) 요청에 대한 처리를 고려해야 할 수도 있어요.

AWS Lambda 예시 (API Gateway 연동):

return {
    statusCode: 200,
    headers: {
        "Access-Control-Allow-Origin": "*",
        "Access-Control-Allow-Methods": "GET,POST,OPTIONS",
        "Access-Control-Allow-Headers": "Content-Type"
    },
    body: JSON.stringify({ message: "CORS 허용 완료" })
};
    

🌐 실무 팁

• 로컬 개발 중이라면 모든 Origin을 허용해도 괜찮지만, 운영 환경에서는 정해진 도메인만 허용하는 것이 안전합니다.
• 브라우저가 자동으로 보내는 OPTIONS 요청(프리플라이트 요청)에 주의해야 합니다. 이 요청에 대한 응답도 제대로 설정되어야 CORS 문제가 발생하지 않아요.
• 인증이 필요한 API의 경우 credentials: true 옵션을 반드시 함께 설정하고, Access-Control-Allow-Credentials 헤더도 서버에서 포함해야 합니다.

정리하자면, CORS 문제는 서버와 클라이언트 간의 신뢰 관계를 명시해 주는 설정만으로도 충분히 해결할 수 있습니다. 그러나 클라우드 환경, 인증 처리, 서버리스 구조 등 상황에 따라 보다 정교한 설정이 필요할 수 있어요.

마무리하며

CORS 에러는 웹 개발 과정에서 가장 자주 접하게 되는 이슈 중 하나입니다. 하지만, 그 원인을 정확히 이해하고 적절한 설정을 통해 대응한다면 충분히 쉽게 해결할 수 있어요. Node.js에서 cors 미들웨어를 사용하는 방법은 그 중 가장 기본적이고 강력한 해결책입니다.

또한 최근의 클라우드 기반 개발 환경에서는 각 플랫폼에 맞는 방식으로 CORS를 설정하는 것이 필수입니다. 무조건 모든 요청을 허용하기보다는, 보안과 확장성을 고려해 도메인 화이트리스트 기반 접근 제어를 하는 것이 장기적으로 안정적인 운영에 도움이 됩니다.

📚 더 알아보기: 공식 CORS 문서

🏷️ 태그

Node.js, CORS, CORS 에러, 백엔드 개발, 웹 보안, Express.js, 서버 설정, 클라우드 서버, API Gateway, AWS Lambda