스토리지에 파일 올리기

내 서비스의 사용자 파일(이미지 · 문서)을 내 버킷에 올릴 때 써요. 버킷 키는 리소스가 갖고, 브라우저나 앱은 잠깐 쓰는 업로드 주소로 버킷에 바로 올려요.

1. 스토리지 리소스 만들기

1. 프로젝트 › Storage › 리소스 추가 에서 AWS S3 또는 Cloudflare R2 를 골라 만들어요
2. 리소스 상세 › 설정 · 자격증명 에 값을 넣고 설정 저장 을 눌러요

그다음 이 리소스로 토큰을 받아요 → 내 서비스에서 리소스 쓰기

2. 올리고 확정하기

올리기는 세 단계예요. 업로드 주소 받기 → 그 주소로 올리기 → 확정.

const zc = createZeroCloudClient({
  baseUrl: 'https://api.zerocloud.im',
  storage: {
    baseUrl: '<개발자 센터의 스토리지 API 주소>',
    resourceId: process.env.STORAGE_RESOURCE_ID!,
    resourceToken: process.env.STORAGE_RESOURCE_TOKEN!,
  },
});

// 1) 업로드 주소 — 응답에 url 과 id 가 와요
const up = (await zc.storage.presignedUrl({
  key: 'uploads/2026/photo.png',
  operation: 'upload',
  contentType: 'image/png',
  contentLength: file.size,
})) as { url: string; id: string };

// 2) 그 url 로 파일을 PUT 해요 (브라우저에서 바로 해도 돼요)

// 3) 확정 — 받은 id 에 내 서비스의 키(예: 상품 번호)를 붙여요
await zc.storage.commit({ ids: [up.id], fileKey: 'PRODUCT_123' });

• contentLength 를 넣으면 그 크기로 서명돼요. 다른 크기의 파일을 올리면 버킷이 거절해요 — 넣는 걸 권해요
• 확정하지 않은 파일은 「임시 업로드」 로 남아요. 확정해야 그 키로 찾을 수 있어요
• 같은 fileKey 에 다시 확정하면 기존 파일은 그대로 두고 새 파일이 더해져요
• 이미 확정한 파일을 다른 키로 옮길 때는 zc.storage.rebind 를 써요

3. 내려받기 · 목록

• 내려받기 주소: presignedUrl({ key, operation: 'download' }). 브라우저에서 바로 열려면 disposition: 'inline'
• 확정한 파일 보기: zc.storage.get(fileKey) · 목록 zc.storage.list()

끝났는지 확인

zc.storage.get('PRODUCT_123') 에 방금 올린 파일이 보이면 끝이에요.

막히면 → 자주 막히는 곳