turin's blog
만들고, 터지고,
기록합니다
풀스택, Flutter, 서버 운영, SEO, 배포 삽질을 실제 프로젝트 기준으로 정리합니다. 검색해서 들어온 사람이 바로 쓸 수 있는 체크리스트와 명령을 남기는 게 목표입니다.
자주 다루는 주제
주제별로 빠르게 훑어보기
전체 글
운영 중 부딪힌 문제를 검색 의도에 맞춰 정리
API 응답에서 DTO의 필드가 null이 돼서 터질 때 배포 전 확인
인증, 응답 바디, 필드 정의를 차례대로 확인하면 null 때문의 런타임 에러는 배포 전에 잡을 수 있다.
관리자 API가 로컬에선 되는데 서버에선 실패할 때
포트, 권한, 프로세스 상태를 순서대로 확인하면 운영 서버의 API 문제는 대부분 분명해진다.
계속 읽기 →Flutter 모바일 앱에서 key prop으로 인한 레이아웃 깨짐 문제
Flutter의 key는 위젯 상태를 유지하는 중요한 장치다. 레이아웃이 깨질 때는 key 설정, 빌드 모드, flutter doctor부터 확인한다.
계속 읽기 →middleware 문제를 검색해서 바로 따라 하다 막힐 때
middleware는 요청 흐름의 중간에 끼어 있기 때문에, 문제가 발생하면 로컬과 운영 환경의 차이를 먼저 의심해야 한다.
계속 읽기 →관리자 기능에 validation을 추가할 때 운영상 점검 항목
API 요청 파라미터, 상태 코드, 응답 바디를 체계적으로 확인하면 validation 로직의 문제를 신속하게 찾을 수 있다.
계속 읽기 →TypeScript 유니온 타입 다룰 때 타입 가드 순서가 중요한 이유
optional, null, 타입 정의를 체계적으로 확인해야 런타임 에러를 줄일 수 있다. 타입 체크는 일찍 할수록 좋다.
계속 읽기 →로컬에선 작동하는데 서버 푸시 알림이 안 올 때
푸시 알림 실패는 인증, 권한, 설정 문제인 경우가 대부분. 환경 차이를 체계적으로 확인하면 원인이 명확해진다.
계속 읽기 →개발 환경에선 멀쩡한데 서버에서만 터지는 날짜 처리 문제
타임존, 날짜 형식, 데이터 타입 불일치. 로컬과 서버의 환경 차이는 보통 시간 관련 코드에서 드러난다.
계속 읽기 →Next.js에서 조건부 렌더링이 늦거나 틀릴 때 체크포인트
메타데이터와 캐노니컬 태그, 그리고 빌드 결과를 차례대로 확인하면 Next.js의 조건부 렌더링 문제는 쉽게 풀린다.
계속 읽기 →앱 버전 호환성 문제를 파악하는 차근차근한 방법
앱 버전 때문에 일어나는 문제들은 환경 차이에서 비롯되는 경우가 많다. 먼저 설정을 확인하고 한 단계씩 진행하면 길을 잃지 않는다.
계속 읽기 →동적 렌더링이 예상과 다를 때 진짜 원인 찾기
화면에 콘텐츠가 제대로 나타나지 않을 때, 로그와 응답을 함께 봐야 한다. 시각적 확인만으로는 원인의 절반만 본다.
계속 읽기 →Docker의 Node.js 컨테이너 문제를 체계적으로 좁혀가기
Node.js 컨테이너가 예상과 다르게 동작할 때, 무작정 설정을 만지기보다는 포트·환경변수·로그 순서대로 확인하면 원인을 훨씬 빠르게 찾을 수 있다.
계속 읽기 →연결 문자열(Connection String) 오류를 배포 전에 잡기
데이터베이스 연결 문자열은 환경마다 다르고, 타이핑 실수가 쉽다. 배포 전에 한 번이라도 테스트해야 한다.
계속 읽기 →TypeScript 유니온 타입을 안전하게 변경하는 방법
기존 코드를 깨지 않으면서 타입을 확장하려면, 단계적 마이그레이션이 필수다.
계속 읽기 →서버 로그가 로테이션된 후 확인할 것
배포 직후 로그가 자동 삭제되면 문제 추적이 불가능해진다. 로그 보관 정책을 미리 확인해두자.
계속 읽기 →API 응답의 null값이 런타임 에러를 일으킨다면
백엔드와 프론트엔드의 타입 정의가 일치하지 않으면, 문제는 배포 후에 터진다.
계속 읽기 →React 컴포넌트 에러 메시지가 유저에게 노출되면 안 된다
에러를 보여줄 때 기술적 상세는 숨기고, 사용자가 이해할 수 있는 메시지만 노출해야 한다.
계속 읽기 →Next.js 서버 액션은 정말 서버에서 실행되는가?
서버 액션을 썼다면, 실제로 서버에서만 실행되는지 빌드 로그와 응답으로 확인해야 한다.
계속 읽기 →빌드 시간이 자꾸 길어질 땐 병목부터 찾자
릴리즈 빌드가 느려지는 건 보통 몇 가지 원인만 반복된다. 각 단계를 측정해보면 어디가 문제인지 명확하다.
계속 읽기 →Next.js OG 이미지가 안 보일 땐 어디를 확인할까
Next.js의 OG 이미지는 서버에서 렌더링되기 때문에, 클라이언트 환경만으로는 문제를 알 수 없다.
계속 읽기 →Docker 빌드가 자꾸 실패하면 컨텍스트부터 확인하자
Docker 빌드 실패는 대부분 이미지, 로그, 환경변수 중 하나만 확인하면 원인을 찾을 수 있다.
계속 읽기 →배포 직전에 꼭 확인해야 할 웹 개발 체크리스트
배포 전 5분 정도 걸리는 체크리스트를 미리 정해두면, 배포 후 문제가 생길 확률을 크게 줄일 수 있다.
계속 읽기 →API 요청이 느려지면 CORS 확인부터 시작하자
CORS 설정 문제는 API 속도 저하의 의외로 흔한 원인이다. 브라우저 요청의 전체 흐름을 파악하면 빠르게 진단할 수 있다.
계속 읽기 →Prisma 마이그레이션이 꼬일 때 확인할 순서
DB 마이그레이션 중 동작하지 않을 땐 간단한 확인부터 시작하면 원인을 빠르게 찾을 수 있다.
계속 읽기 →