🚀 Next.js + Firebase로 만드는 풀스택 웹앱 실전 프로젝트

🎯 목표

Storage 보안 규칙으로 사용자 디렉터리 단위 권한 설정
썸네일 업로드/미리보기/교체/삭제 구현
Firestore posts 문서에 thumbUrl, thumbPath 필드 저장/동기화

0) Storage 규칙 (개발용 → 실전에도 사용 가능)

Firebase Console → Storage → 규칙에 적용:

// Storage Rules
rules_version = '2';
service firebase.storage {
  match /b/{bucket}/o {
    // 각 사용자의 전용 폴더
    match /users/{uid}/{allPaths=**} {
      // 읽기: 공개 서비스면 true, 내부 서비스면 제한 가능
      allow read: if true;

      // 쓰기/삭제: 본인만 가능
      allow write: if request.auth != null && request.auth.uid == uid;
    }
  }
}

목적

users/{uid}/** 경로에 대해 소유자만 쓰기/삭제 가능, 공개 읽기는 허용(필요 시 제한)합니다.

동작 원리

match /users/{uid}/{allPaths=**}: 사용자별 최상위 디렉터리를 UID로 네임스페이스화합니다.
allow read: if true;: 학습/데모 목적의 공개 읽기. 실전에서는 다운로드 권한을 세분화(예: 포스팅 썸네일만 공개)하는 것이 좋습니다.
allow write: if request.auth != null && request.auth.uid == uid;

→ 로그인 + 자신의 UID 경로에서만 업로드/삭제 가능. 타인의 경로 접근은 차단됩니다.

경로 전략

users/{uid}/posts/{postId}/{filename}

→ 글 단위로 폴더를 분리해 정리/정책/삭제(정리) 작업이 간단해집니다.

실전 팁

썸네일만 공개할 경우, 썸네일 경로만 공개 읽기, 원본은 비공개로 두고 서버(또는 Cloud Functions)로 서명 URL을 발급하는 방식도 고려하세요.

1) 업로드/삭제 유틸

lib/storage.ts

'use client';

import { storage } from '@/lib/firebase.client';
import { ref, uploadBytes, getDownloadURL, deleteObject } from 'firebase/storage';

export async function uploadImageByPath(file: File, fullPath: string) {
  const fileRef = ref(storage, fullPath);
  const snap = await uploadBytes(fileRef, file, {
    contentType: file.type || 'application/octet-stream',
    cacheControl: 'public,max-age=31536000,immutable',
  });
  const url = await getDownloadURL(snap.ref);
  return { url, path: snap.ref.fullPath };
}

export async function deleteByPath(path?: string) {
  if (!path) return;
  try {
    await deleteObject(ref(storage, path));
  } catch (e) {
    // 없는 파일일 수 있으므로 조용히 무시
    console.warn('deleteByPath warning:', e);
  }
}

uploadImageByPath(file, fullPath)

역할: 주어진 fullPath로 파일을 업로드하고, 즉시 다운로드 URL과 fullPath를 반환합니다.
업로드 옵션
- contentType: 브라우저 미리보기·캐시 동작을 위해 지정
- cacheControl: public,max-age=31536000,immutable
  
  → 썸네일은 변경보다 추가/교체가 많으므로 강한 캐시 전략이 유리합니다(교체 시 새 파일명으로 캐시 무효화).

deleteByPath(path)

역할: fullPath로 객체 삭제.
예외 처리: “이미 없어진 파일”일 수 있으므로 catch 후 경고만 기록하고 무시합니다(UX 저해 방지)

2) 이미지 선택 컴포넌트 (미리보기 포함)

components/ImagePicker.tsx

'use client';

import { useEffect, useRef, useState } from 'react';

type Props = {
  initialUrl?: string;
  onFileChange: (file: File | null) => void;
  accept?: string;
  maxSizeMB?: number;
};

export default function ImagePicker({
  initialUrl,
  onFileChange,
  accept = 'image/*',
  maxSizeMB = 5,
}: Props) {
  const inputRef = useRef<HTMLInputElement | null>(null);
  const [preview, setPreview] = useState<string | undefined>(initialUrl);
  const [err, setErr] = useState<string | null>(null);

  useEffect(() => setPreview(initialUrl), [initialUrl]);

  const handlePick = (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0] ?? null;
    if (!file) {
      onFileChange(null);
      setPreview(initialUrl);
      return;
    }
    if (!file.type.startsWith('image/')) {
      setErr('이미지 파일만 업로드할 수 있습니다.');
      onFileChange(null);
      return;
    }
    if (file.size > maxSizeMB * 1024 * 1024) {
      setErr(`파일 용량은 최대 ${maxSizeMB}MB까지 가능합니다.`);
      onFileChange(null);
      return;
    }
    setErr(null);
    onFileChange(file);
    const url = URL.createObjectURL(file);
    setPreview(url);
  };

  const clear = () => {
    if (inputRef.current) inputRef.current.value = '';
    onFileChange(null);
    setPreview(initialUrl);
  };

  return (
    <div style={{ display: 'grid', gap: 8 }}>
      <div style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
        <input ref={inputRef} type="file" accept={accept} onChange={handlePick} />
        {preview && (
          <button type="button" onClick={clear} style={{ padding: '6px 10px', borderRadius: 8 }}>
            선택 해제
          </button>
        )}
      </div>
      {err && <p style={{ color: 'crimson', fontSize: 13 }}>{err}</p>}
      {preview && (
        <img src={preview}
          alt="preview"
          style={{ width: 220, height: 140, objectFit: 'cover', borderRadius: 10, border: '1px solid #eee' }}
        />
      )}
    </div>
  );
}

역할

사용자가 파일을 선택하면 유효성 검사(타입/용량) → 미리보기 URL 생성 → 부모에 File 전달.
initialUrl이 있으면(수정 화면) 최초 미리보기로 표시합니다.

흐름

input[type=file] 변경 이벤트에서 파일 추출
이미지 타입인지 확인 (file.type.startsWith('image/'))
최대 용량(MB) 제한 검사
통과 시 URL.createObjectURL(file)로 로컬 미리보기 생성
“선택 해제” 클릭 시 선택 취소 + 미리보기 초기화

UX 팁

모바일 환경에서 대용량 업로드를 방지하려면 maxSizeMB를 낮게 설정하거나 클라이언트 리사이즈(Canvas/Compressor) 전략을 추가해도 좋습니다.

3) 타입 확장

types/post.ts

export type Post = {
  id: string;
  uid: string;
  title: string;
  content?: string;
  isPublic: boolean;
  thumbUrl?: string;  // 썸네일 URL
  thumbPath?: string; // Storage fullPath (삭제/교체용)
  createdAt?: { seconds: number; nanoseconds: number } | null;
  updatedAt?: { seconds: number; nanoseconds: number } | null;
};

추가 필드

thumbUrl?: string : Storage의 공개(또는 접근 가능한) URL
thumbPath?: string: fullPath(예: users/{uid}/posts/{postId}/...) → 삭제/교체 시 필수

설계 포인트

URL은 캐시 대상이므로, 이미지 교체 시 파일명을 바꿔 업로드하고 문서의 thumbUrl만 갱신하면 캐시 문제가 없습니다.

4) PostForm에 이미지 필드 추가

components/PostForm.tsx (변경)

'use client';

import { useState, FormEvent } from 'react';
import ImagePicker from './ImagePicker';

type Props = {
  initial?: {
    title?: string;
    content?: string;
    isPublic?: boolean;
    thumbUrl?: string;
  };
  submitText?: string;
  onSubmit: (data: {
    title: string;
    content: string;
    isPublic: boolean;
    file: File | null; // 추가: 업로드할 파일
  }) => Promise<void>;
};

export default function PostForm({
  initial,
  submitText = '저장',
  onSubmit,
}: Props) {
  const [title, setTitle] = useState(initial?.title ?? '');
  const [content, setContent] = useState(initial?.content ?? '');
  const [isPublic, setIsPublic] = useState(initial?.isPublic ?? true);
  const [file, setFile] = useState<File | null>(null);
  const [loading, setLoading] = useState(false);
  const [err, setErr] = useState<string | null>(null);

  const handle = async (e: FormEvent) => {
    e.preventDefault();
    if (!title.trim()) return setErr('제목을 입력하세요.');
    setErr(null);
    setLoading(true);
    try {
      await onSubmit({
        title: title.trim(),
        content: content.trim(),
        isPublic,
        file,
      });
    } catch (e: any) {
      setErr(e?.message ?? '저장 실패');
    } finally {
      setLoading(false);
    }
  };

  return (
    <form onSubmit={handle} style={{ display: 'grid', gap: 12 }}>
      <input
        placeholder='제목'
        value={title}
        onChange={(e) => setTitle(e.target.value)}
        style={{ padding: 10, border: '1px solid #ddd', borderRadius: 8 }}
      />
      <textarea
        placeholder='내용(선택)'
        value={content}
        onChange={(e) => setContent(e.target.value)}
        rows={8}
        style={{ padding: 10, border: '1px solid #ddd', borderRadius: 8 }}
      />

      {/* 썸네일 업로드 */}
      <div>
        <label style={{ display: 'block', marginBottom: 6, fontWeight: 600 }}>
          썸네일
        </label>
        <ImagePicker initialUrl={initial?.thumbUrl} onFileChange={setFile} />
      </div>

      <label style={{ display: 'flex', gap: 8, alignItems: 'center' }}>
        <input
          type='checkbox'
          checked={isPublic}
          onChange={(e) => setIsPublic(e.target.checked)}
        />
        공개글로 등록
      </label>

      {err && <p style={{ color: 'crimson', fontSize: 14 }}>{err}</p>}

      <button
        disabled={loading}
        style={{ padding: '10px 12px', borderRadius: 8 }}
      >
        {loading ? '처리 중…' : submitText}
      </button>
    </form>
  );
}

변경점

onSubmit에 file: File | null 추가 → 폼 단에서 이미지 선택 여부를 상위로 전달.
ImagePicker를 포함해 최초 썸네일(initial.thumbUrl) 미리보기와 교체를 지원.

제출 흐름

제목 공백 체크
onSubmit({ title, content, isPublic, file }) 호출
상위(페이지)에서 업로드/문서 업데이트를 처리 → 관심사 분리

5) 새 글 작성: 업로드 → 문서 생성

app/posts/new/page.tsx (업데이트)

'use client';

import { useRouter } from 'next/navigation';
import { addDoc, collection, serverTimestamp } from 'firebase/firestore';
import { db } from '@/lib/firebase.client';
import { uploadImageByPath } from '@/lib/storage';
import PostForm from '@/components/PostForm';
import { useAuth } from '@/hooks/useAuth';

export default function NewPostPage() {
  const router = useRouter();
  const { user, loading } = useAuth();

  if (loading) return null;
  if (!user) {
    router.replace('/login');
    return null;
  }

  const create = async (data: {
    title: string;
    content: string;
    isPublic: boolean;
    file: File | null;
  }) => {
    // 일단 문서부터 만들고 postId를 얻어 경로를 안정적으로 구성
    const docRef = await addDoc(collection(db, 'posts'), {
      uid: user.uid,
      title: data.title,
      content: data.content,
      isPublic: data.isPublic,
      createdAt: serverTimestamp(),
      updatedAt: serverTimestamp(),
      thumbUrl: null,
      thumbPath: null,
    });

    let thumbUrl: string | null = null;
    let thumbPath: string | null = null;

    if (data.file) {
      const fileName = `${Date.now()}-${data.file.name}`;
      const fullPath = `users/${user.uid}/posts/${docRef.id}/${fileName}`;
      const uploaded = await uploadImageByPath(data.file, fullPath);
      thumbUrl = uploaded.url;
      thumbPath = uploaded.path;

      // 썸네일 정보만 업데이트
      await (
        await import('firebase/firestore')
      ).updateDoc(docRef, {
        thumbUrl,
        thumbPath,
        updatedAt: serverTimestamp(),
      });
    }

    router.replace(`/posts/${docRef.id}`);
  };

  return (
    <main style={{ maxWidth: 720, margin: '40px auto', padding: 16 }}>
      <h1>새 글 작성</h1>
      <PostForm onSubmit={create} submitText='등록' />
    </main>
  );
}

핵심 전략

먼저 문서 생성 → postId 확보 → 그 postId로 경로 구성하여 업로드 → 문서 업데이트

→ 경로가 안정적이고, 중간 실패 시 롤백(문서 삭제)도 명확합니다.

흐름

로그인 확인(미로그인 시 /login으로 replace)
addDoc으로 문서 생성(초기 thumbUrl/thumbPath는 null)
파일이 있으면 users/{uid}/posts/{docId}/{timestamp-name}로 업로드
- 업로드 성공 시 thumbUrl, thumbPath를 updateDoc으로 반영
완료 후 상세 페이지로 replace

실전 팁

업로드 실패 시 문서만 남는 상황을 피하려면, try/catch로 업로드 실패 시 문서를 삭제하거나 thumb 없는 상태도 유효한 스키마로 인정하세요.

6) 상세/수정: 교체 업로드 + 기존 파일 삭제

app/posts/[id]/page.tsx (중요 부분만 갱신)

'use client';

import { useEffect, useState } from 'react';
import { useParams, useRouter } from 'next/navigation';
import { auth, db } from '@/lib/firebase.client';
import {
  deleteDoc,
  doc,
  getDoc,
  updateDoc,
  serverTimestamp,
} from 'firebase/firestore';
import { onAuthStateChanged } from 'firebase/auth';
import type { Post } from '@/types/post';
import PostForm from '@/components/PostForm';
import { deleteByPath, uploadImageByPath } from '@/lib/storage';

export default function PostDetailPage() {
  const { id } = useParams<{ id: string }>();
  const router = useRouter();
  const [post, setPost] = useState<Post | null>(null);
  const [uid, setUid] = useState<string | null>(null);
  const [editing, setEditing] = useState(false);

  useEffect(() => onAuthStateChanged(auth, (u) => setUid(u?.uid ?? null)), []);
  useEffect(() => {
    const load = async () => {
      const snap = await getDoc(doc(db, 'posts', id));
      if (!snap.exists()) return router.replace('/posts');
      setPost({ id: snap.id, ...(snap.data() as any) });
    };
    load();
  }, [id, router]);

  const isOwner = uid && post && uid === post.uid;

  const update = async (data: {
    title: string;
    content: string;
    isPublic: boolean;
    file: File | null;
  }) => {
    if (!post) return;

    let nextThumbUrl = post.thumbUrl ?? null;
    let nextThumbPath = post.thumbPath ?? null;

    // 파일 교체가 있으면 새로 업로드 → 이전 파일 삭제
    if (data.file && uid) {
      const fileName = `${Date.now()}-${data.file.name}`;
      const fullPath = `users/${uid}/posts/${post.id}/${fileName}`;
      const uploaded = await uploadImageByPath(data.file, fullPath);
      // 이전 파일 삭제(있으면)
      if (post.thumbPath && post.thumbPath !== uploaded.path) {
        await deleteByPath(post.thumbPath);
      }
      nextThumbUrl = uploaded.url;
      nextThumbPath = uploaded.path;
    }

    await updateDoc(doc(db, 'posts', id), {
      title: data.title,
      content: data.content,
      isPublic: data.isPublic,
      thumbUrl: nextThumbUrl,
      thumbPath: nextThumbPath,
      updatedAt: serverTimestamp(),
    });

    setEditing(false);
    const snap = await getDoc(doc(db, 'posts', id));
    setPost({ id: snap.id, ...(snap.data() as any) });
  };

  const remove = async () => {
    if (!post) return;
    if (!confirm('삭제하시겠습니까?')) return;

    // 파일 먼저 정리(있으면)
    await deleteByPath(post.thumbPath);
    await deleteDoc(doc(db, 'posts', id));
    router.replace('/posts');
  };

  if (!post) return null;

  return (
    <main style={{ maxWidth: 720, margin: '40px auto', padding: 16 }}>
      {!editing ? (
        <>
          <h1>{post.title}</h1>
          {post.thumbUrl && (
            <img
              src={post.thumbUrl}
              alt='thumbnail'
              style={{
                width: '100%',
                maxWidth: 720,
                borderRadius: 12,
                margin: '12px 0',
              }}
            />
          )}
          {post.content && (
            <p style={{ whiteSpace: 'pre-wrap', marginTop: 12 }}>
              {post.content}
            </p>
          )}
          <div style={{ fontSize: 12, opacity: 0.7, marginTop: 8 }}>
            {post.isPublic ? '공개' : '비공개'} · 작성자 {post.uid.slice(0, 6)}…
          </div>
          {isOwner && (
            <div style={{ display: 'flex', gap: 8, marginTop: 16 }}>
              <button
                onClick={() => setEditing(true)}
                style={{ padding: '8px 12px', borderRadius: 8 }}
              >
                수정
              </button>
              <button
                onClick={remove}
                style={{
                  padding: '8px 12px',
                  borderRadius: 8,
                  border: '1px solid #f33',
                  color: '#f33',
                }}
              >
                삭제
              </button>
            </div>
          )}
        </>
      ) : (
        <>
          <h1>글 수정</h1>
          <PostForm
            initial={{
              title: post.title,
              content: post.content,
              isPublic: post.isPublic,
              thumbUrl: post.thumbUrl,
            }}
            submitText='수정 완료'
            onSubmit={update}
          />
          <button onClick={() => setEditing(false)} style={{ marginTop: 12 }}>
            취소
          </button>
        </>
      )}
    </main>
  );
}

수정(교체) 흐름

새 파일을 선택한 경우
- 새 파일명(timestamp-prefix)으로 업로드
- 업로드 성공 후, 이전 thumbPath가 존재하고 서로 다르면 deleteByPath(oldPath)로 정리
- 문서의 thumbUrl, thumbPath 업데이트
파일을 바꾸지 않은 경우
- 텍스트 필드만 업데이트 (updatedAt 갱신)

삭제 흐름

문서 삭제 전, 연결된 파일이 있으면 deleteByPath(post.thumbPath)로 먼저 제거
deleteDoc으로 문서 삭제 → 목록으로 이동

정합성 포인트

“파일 먼저 삭제 → 문서 삭제” 순서로 진행 시, 문서 삭제 실패에도 고아 파일이 줄어듭니다.

반대로 “문서 먼저 삭제” 시 정리 배치(Cloud Functions)로 남은 파일을 삭제하는 비동기 정리 전략도 가능합니다.

7) 목록에서 썸네일 노출(선택)

app/posts/page.tsx의 리스트 아이템에 썸네일 추가:

{posts.map((p) => (
  <li
    key={p.id}
    style={{
      display: 'flex',
      gap: 12,
      border: '1px solid #eee',
      borderRadius: 8,
      padding: 12,
    }}
  >
    {p.thumbUrl && (
      <img
        src={p.thumbUrl}
        alt=''
        style={{
          width: 96,
          height: 64,
          objectFit: 'cover',
          borderRadius: 8,
        }}
      />
    )}
    <div style={{ display: 'grid' }}>
      <Link href={`/posts/${p.id}`} style={{ fontWeight: 600 }}>
        {p.title}
      </Link>
      <div style={{ fontSize: 12, opacity: 0.7, marginTop: 6 }}>
        {p.isPublic ? '공개' : '비공개'} · {p.uid.slice(0, 6)}…
      </div>
    </div>
  </li>
))}

목적

목록에서 thumbUrl이 있으면 작은 썸네일을 함께 노출 → 시각적 탐색성 향상.
이미지 크기는 고정(예: 96×64) + objectFit: 'cover'로 안정적인 카드 레이아웃 유지.

성능 팁

다건 목록의 이미지 로딩에는 loading="lazy"(Next Image 사용 시 loading="lazy" 자동)와 저화질 프리뷰(LQIP) 전략을 고려하세요.

✅ 체크리스트

Storage 규칙 적용 후 users/{uid}/... 경로에 정상 업로드/삭제 가능
새 글 작성 시 이미지 선택 → 업로드 → thumbUrl, thumbPath 저장
수정 시 새 이미지로 교체하면 이전 파일 삭제
글 삭제 시 썸네일 파일도 함께 삭제

썸네일이 잘 등록되는 것까지 확인!

실습저장소

https://github.com/heroyooi/nextjs-firebase

1단계. Next.js + Firebase 실전 앱

1-4. Storage 이미지 업로드 & 게시글 연동