Fuwari Banner
지니제스트Tech Archive
Cloudflare4분 소요

Cloudflare D1과 Astro 연동 가이드

•
ggeniezst

Astro에서 Cloudflare D1 데이터베이스와 R2 스토리지를 연동할 때 겪는 설정 오류와 해결 방법을 공유합니다.

Sponsored

정적 사이트 생성(SSG)과 서버 사이드 렌더링(SSR)을 유연하게 결합할 수 있는 Astro는 Cloudflare의 글로벌 엣지 네트워크(Workers, D1, R2)와 궁합이 매우 좋습니다.

Astro 환경에서 Cloudflare D1과 R2를 바인딩하고, 로컬 개발부터 배포까지 마주쳤던 핵심 설정 이슈와 해결 과정을 정리합니다.

Cloudflare 어댑터와 platformProxy 설정

Astro에서는 로컬 개발 서버에서도 Cloudflare 바인딩(D1, R2, KV 등)을 그대로 에뮬레이션할 수 있는 platformProxy 기능을 제공합니다.

astro.config.mjs에 다음과 같이 어댑터를 설정합니다:

JAVASCRIPT 
import { defineConfig } from 'astro/config';
import cloudflare from '@astrojs/cloudflare';

export default defineConfig({
  output: 'server',
  adapter: cloudflare({
    platformProxy: {
      enabled: true,
    },
  }),
});

이 옵션을 활성화하면 astro dev 실행 시 Astro.locals.runtime.env를 통해 D1과 R2 객체에 로컬에서도 원활하게 접근할 수 있습니다.

D1 바인딩 정의 (wrangler.jsonc)

Cloudflare의 표준 포맷인 wrangler.jsonc에 D1 데이터베이스와 R2 버킷을 지정합니다:

JSONC 
{
  "name": "geniezst-blog",
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "geniezst-blog",
      "database_id": "YOUR_DATABASE_UUID"
    }
  ],
  "r2_buckets": [
    {
      "binding": "BUCKET",
      "bucket_name": "geniezst-blog"
    }
  ]
}

컨테이너 환경 권한 이슈 해결

Docker나 code-server 등 컨테이너 기반 개발 환경에서 프로젝트를 root 권한으로 생성했을 때, 일반 사용자 권한으로 파일을 수정하거나 .env를 저장하면 EACCES: permission denied 오류가 발생할 수 있습니다.

VS Code나 일부 에디터는 파일 저장 시 원자적(atomic) 저장을 위해 상위 디렉토리에 임시 파일을 생성합니다. 따라서 파일뿐만 아니라 디렉토리 자체의 쓰기 권한이 열려 있어야 합니다.

BASH 
chmod 777 /workspace/blog
chmod 666 /workspace/blog/.env

node_modules 전체 소유권을 변경하지 않고 대상 디렉토리와 환경 파일 권한만 조정하면 안전하게 해결됩니다.

Sponsored