Wix Headless API 프로젝트에 Cursor 환경 연결 및 API 키 구성 방법

Wix Headless 및 Cursor API 연동 환경 비교표

Wix Headless API로 구축한 외부 프론트엔드 애플리케이션에 Cursor 관련 AI 기능을 연동할 때, 개발 환경과 연동 방식에 따라 적용되는 조건 및 권한 설정이 다릅니다. 프로젝트 요구사항에 맞춰 API 키 발급 경로와 환경 변수 관리 주체를 먼저 선택합니다.

운영 서버 환경에 배포하는 앱인 경우에는 Wix Headless Client ID와 외부 AI API Key를 모두 백엔드 환경 변수로 승인해야 합니다. 로컬 개발 환경인 경우에는 Cursor IDE 내 Custom API Key 메뉴를 활용해 개발자 개인 키로 테스트를 진행합니다.

환경 변수 설정 및 프로젝트 파일 위치

Wix Headless SDK가 설정된 프로젝트 디렉터리 구조를 확인합니다. Node.js 기반 프레임워크(Next.js 또는 Vite)의 루트 경로에 환경 변수 파일(.env.local)을 생성해야 보안 유출을 방지할 수 있습니다.

wix-headless-app/
├── .env.local             <-- API 키 및 Wix Client ID 저장 위치
├── .gitignore             <-- .env.local 포함 필수
├── package.json
├── src/
│   ├── lib/
│   │   ├── wixClient.ts   <-- @wix/sdk 초기화 코드
│   │   └── aiClient.ts    <-- Cursor/OpenAI 호환 API 호출 코드
│   └── app/
│       └── page.tsx

.gitignore 파일에 .env.local 및 .env가 등록되어 있지 않은 경우에는 Git 저장소로 API 키가 누출되므로 반드시 전송 대상에서 제외합니다.

API 키 연동 및 SDK 호출 설정 5단계 절차

Wix Headless 클라이언트 초기화와 Cursor/OpenAI 호환 API 호출 파이프라인을 구축하는 연속 실행 절차입니다.

1. 터미널을 열고 Wix Headless SDK 및 API 호출용 패키지를 설치합니다.

   npm install @wix/sdk @wix/stores openai
   

2. 프로젝트 루트 위치에 .env.local 파일을 생성하고 아래와 같이 Wix 및 API 키를 작성합니다.

   NEXT_PUBLIC_WIX_CLIENT_ID=your_wix_client_id_here
   OPENAI_API_KEY=your_cursor_or_openai_api_key_here
   OPENAI_BASE_URL=https://openrouter.ai/api/v1
   

3. src/lib/wixClient.ts 파일을 생성하여 Wix Headless API 클라이언트를 초기화합니다.

   import { createClient, OAuthStrategy } from '@wix/sdk';
   import { products } from '@wix/stores';
   
   export const wixClient = createClient({
     modules: { products },
     auth: OAuthStrategy({
       clientId: process.env.NEXT_PUBLIC_WIX_CLIENT_ID!,
     }),
   });
   

4. src/lib/aiClient.ts 파일을 생성하여 Cursor 연동용 OpenAI SDK 호환 클라이언트를 작성합니다.

   import OpenAI from 'openai';
   
   export const aiClient = new OpenAI({
     apiKey: process.env.OPENAI_API_KEY,
     baseURL: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
   });
   

5. 터미널에서 개발 서버를 실행하여 로딩 오류가 발생하는지 확인합니다.

   npm run dev
   

   콘솔에 Ready in [ms] 문구가 출력되면 기본 환경 연결이 정상적으로 완료된 상태입니다.

저장소 제출 시 보안 권한 및 제외 설정

API 키 유출을 막기 위해 소스 코드 내부에 하드코딩된 Secret Key 값은 모두 삭제해야 합니다. Wix Headless API 구축 시 발급되는 OAuth Client Secret이나 OpenAI/Cursor API 키는 클라이언트 브라우저로 노출되지 않도록 서버 사이드(API Route 또는 Server Actions)에서만 접근해야 합니다.

NEXT_PUBLIC_ 접두사가 붙은 환경 변수는 브라우저 번들 파일에 직접 포함됩니다. 따라서 Wix Client ID를 제외한 모든 비밀키에는 NEXT_PUBLIC_ 접두사를 절대 사용하지 않습니다.

API 연결 오류 진단 및 원인 분석표

연동 과정에서 발생하는 대표적인 4가지 오류 상태와 확인 방법, 즉시 적용 가능한 복구 조치 안내입니다.

지속적으로 401 오류가 발생하는 경우에는 계정 사용 한도를 초과했거나 결제 수단이 등록되지 않은 상태일 수 있으므로 서비스 제공자 대시보드에서 잔여 트래픽을 확인합니다.

연동 정상 동작 검증 및 테스트 방법

연동 작업이 올바르게 완료되었는지 검증하려면 Wix Headless에서 상품 목록을 가져와 AI 모델의 프롬프트 입력으로 전달하는 통합 테스트를 수행합니다.

터미널에서 npm run dev 명령어로 개발 서버를 띄운 뒤, 테스트 페이지에 접속하여 HTTP 200 OK 응답과 함께 Wix 상품 데이터 기반의 AI 생성 텍스트가 화면에 표시되는지 확인합니다. 브라우저 개발자 도구 Network 탭에서 API Key가 헤더나 URL 파라미터에 직접 노출되지 않고 서버 단에서 처리되는지 검수합니다.

클라이언트 단에서 API 키가 그대로 노출되는 경우에는 서버 사이드 API 경로로 로직을 완전히 이전해야 하며, 외부 프록시 서버 연동이 불가능한 구조라면 Supabase Edge Functions 또는 Vercel Serverless Functions를 대안 레이어로 구성합니다.