turin's blog
만들고, 터지고,
기록합니다
풀스택, Flutter, 서버 운영, SEO, 배포 삽질을 실제 프로젝트 기준으로 정리합니다. 검색해서 들어온 사람이 바로 쓸 수 있는 체크리스트와 명령을 남기는 게 목표입니다.
자주 다루는 주제
주제별로 빠르게 훑어보기
전체 글
운영 중 부딪힌 문제를 검색 의도에 맞춰 정리
Docker 이미지 용량 제한을 두는 이유와 방법
배포 환경에서 Docker 이미지가 과도하게 커지는 것을 방지하는 방법을 정리했다.
Next.js middleware matcher 범위를 좁게 설정해야 하는 이유
Next.js middleware의 matcher 설정이 너무 넓으면 성능 문제와 예상 밖의 동작이 발생한다.
계속 읽기 →DB 마이그레이션: 먼저 백업하고 시작하기
데이터베이스 마이그레이션 전에 확인해야 할 백업 절차와 복구 계획을 정리했다.
계속 읽기 →GitHub 토큰을 깃 설정에 안전하게 보관하기
git config에 GitHub 토큰을 저장할 때 실수하기 쉬운 부분과 안전한 방법을 정리했다.
계속 읽기 →Next.js 블로그: SEO 메타데이터 제대로 확인하기
Next.js 블로그의 제목, 설명, canonical 태그가 제대로 렌더링되지 않을 때 확인해야 할 항목들을 정리했다.
계속 읽기 →운영 환경 로그에서 debug 레벨을 걸러내야 하는 이유
개발 중 디버깅에 편했던 verbose 로그를 운영에서 그대로 켜두면 성능과 비용, 보안 세 가지에 모두 영향을 미친다.
계속 읽기 →React list에서 key를 index 대신 id로 써야 하는 이유
key={index}는 경고를 없애주지만 문제를 해결하지는 않는다. 항목 순서가 바뀌거나 삭제될 때 컴포넌트 상태가 엉킬 수 있다.
계속 읽기 →Next.js sitemap.xml에 새 글이 빠지는 이유와 확인 방법
Next.js에서 sitemap을 정적으로 생성하면 빌드 시점의 글만 포함된다. 글을 발행한 뒤 사이트맵이 갱신됐는지 직접 확인하는 것이 필요하다.
계속 읽기 →Node.js 빌드가 서버에서 죽는다면 메모리부터 확인한다
로컬에서 잘 되던 npm run build가 서버에서 갑자기 죽으면 십중팔구 메모리 문제다. OOM killer 로그와 swap 설정을 먼저 확인한다.
계속 읽기 →Nginx 설정을 include로 나눠두면 관리가 편해진다
모든 서버 블록을 nginx.conf 한 파일에 쌓으면 길이가 금방 수백 줄이 된다. include 지시어로 파일을 나누면 수정할 때 찾기 쉽고 nginx -t 검증도 빠르다.
계속 읽기 →API 목록 정렬: createdAt과 updatedAt 어느 쪽을 기본으로 할까
createdAt 정렬은 순서가 고정되어 페이지네이션에 안정적이고, updatedAt 정렬은 최근 활동 순으로 보여주기 좋다. 용도에 따라 다르게 선택해야 한다.
계속 읽기 →Git 커밋을 작게 나누면 나중에 고생이 줄어든다
커밋 하나에 여러 변경을 몰아넣으면 revert할 때도, bisect로 버그를 찾을 때도 단위가 너무 커서 힘들어진다. 작은 커밋은 나중의 나를 위한 배려다.
계속 읽기 →404 페이지가 막다른 길이 되지 않게 하기
404 페이지에 홈 링크 하나 없으면 사용자는 뒤로 가기 버튼을 눌러 이탈한다. 최소한의 탈출구를 만들어두는 것이 맞다.
계속 읽기 →.dockerignore 없이 빌드하면 이미지가 왜 커지는가
.dockerignore를 설정하지 않으면 node_modules나 .git 같은 폴더가 통째로 이미지에 포함된다. 이미지 크기와 빌드 시간, 보안 모두 영향을 받는다.
계속 읽기 →Next.js에서 Client Component 범위를 최소화하는 방법
'use client'를 파일 상단에 붙이면 그 파일 전체와 하위 트리가 클라이언트 번들에 포함된다. 컴포넌트를 작게 쪼개야 하는 이유가 여기에 있다.
계속 읽기 →새로고침해도 변경이 안 보일 때 — 브라우저 캐시와 hard reload
일반 새로고침은 캐시된 파일을 그대로 쓴다. 배포 직후 변경이 반영되지 않아 보인다면 hard reload로 캐시를 건너뛰어야 한다.
계속 읽기 →robots.txt에서 /admin은 막고 /posts는 여는 설정
robots.txt를 제대로 관리하지 않으면 관리자 페이지가 검색엔진에 노출되거나, 글 목록이 색인에서 빠지는 상황이 생긴다.
계속 읽기 →CI에서 npm install 대신 npm ci를 써야 하는 이유
npm ci는 package-lock.json을 기준으로 정확히 설치하고 일관성을 보장한다. CI 환경에서 npm install을 쓰면 lockfile과 달라진 패키지가 들어올 수 있다.
계속 읽기 →React 폼 에러 메시지를 입력창 바로 아래에 두는 이유
에러 메시지를 폼 상단에 몰아두면 모바일에서 어디가 잘못됐는지 찾기 힘들다. 각 입력창 바로 아래에 두는 것이 사용성 면에서 훨씬 낫다.
계속 읽기 →nginx 리다이렉트 설정 변경 후 curl로 검증하는 방법
브라우저 캐시 때문에 리다이렉트 결과를 믿으면 안 된다. curl -IL로 실제 응답 체인을 직접 확인하는 것이 정확하다.
계속 읽기 →.env.example을 실제 .env와 함께 관리해야 하는 이유
.env.example이 오래 방치되면 새 환경에서 배포할 때 환경변수 누락으로 조용히 실패한다. 실제 .env를 바꿀 때 example도 같이 업데이트하는 게 습관이 돼야 한다.
계속 읽기 →SQLite 파일 경로를 README에 명시해둬야 하는 이유
SQLite는 경로가 틀리면 새 DB 파일을 조용히 만들어버린다. 이 특성 때문에 파일 위치를 문서에 적어두지 않으면 나중에 디버깅이 복잡해진다.
계속 읽기 →Tailwind에서 색상 변수를 config에 정의해두면 좋은 점
Tailwind 색상을 config에 토큰으로 정의해두면 일관성 유지와 팔레트 교체 모두 한결 쉬워진다.
계속 읽기 →혼자 만드는 프로젝트에도 main 브랜치 보호를 거는 이유
팀 없이 혼자 개발해도 main 브랜치 보호 규칙 하나가 실수로 인한 직접 push와 CI 우회를 막아준다.
계속 읽기 →