범인은 경로가 아니라 CSP(Content Security Policy) 입니다

개발을 하다 보면 한 번쯤 이런 상황을 겪으셨을 겁니다.

“파일도 있고, 경로도 맞는데 왜 이미지가 안 나오지…?”

분명히 dist-electron 안에 파일도 있고,

상대 경로도 맞는데…

이미지가 안 보입니다.

이럴 때 대부분 이렇게 생각합니다.

1. 경로 문제인가?
2. 빌드 문제인가?
3. asar 문제인가?

그런데 의외로 진짜 원인은 따로 있습니다.

👉 CSP(Content Security Policy)

오늘은 이 CSP가 무엇인지,

그리고 왜 Electron에서 자주 문제를 일으키는지

재밌고 쉽게 정리해보겠습니다.

CSP 한 줄 정리

“이 페이지에서 어떤 것만 실행해도 되는지 미리 정해두는 보안 규칙”

1. 왜 이런 게 필요할까요?

웹에는 아주 유명한 공격이 하나 있습니다.

XSS (스크립트 삽입 공격)

예를 들어 어떤 입력창에 이런 코드가 들어왔다고 가정해보겠습니다.

<scriptsrc="https://evil.com/hack.js"></script>

CSP가 없다면 브라우저는 이렇게 생각합니다.

오 스크립트네?
→ 실행

결과는…?

• 쿠키 탈취
• 세션 탈취
• 계정 해킹

CSP가 있으면?

script-src 'self'

브라우저 판단:

👉 즉, 허용된 것만 실행됩니다

2. CSP의 핵심 개념 (이거 하나면 끝입니다)

CSP = 허용된 것만 된다

3. CSP는 어떻게 생겼을까요?

보통 HTML에 이렇게 들어갑니다.

<metahttp-equiv="Content-Security-Policy"
content="default-src 'self'">

이걸 해석하면

"우리 것만 써"

입니다.

4. 주요 규칙 구조

CSP는 리소스별로 따로 설정할 수 있습니다.

5. 허용 값 종류

6. 그럼 왜 내 이미지가 안 나왔을까요?

여기서 핵심입니다.

현재 상황

<metacontent="default-src 'self'">

그리고 코드

<imgsrc="data:image/png;base64,..."/>

브라우저 내부 판단 과정

콘솔 에러

Refused to load image because it violates CSP

7. 해결 방법

딱 한 줄입니다.

img-src 'self' data:

수정 후

<metahttp-equiv="Content-Security-Policy"
content="default-src 'self'; img-src 'self' data:;">

의미

👉 보안은 유지하면서 문제만 해결됩니다

8. Electron에서 특히 자주 터지는 이유

Electron은 그냥 앱처럼 보이지만 내부는 이겁니다.

Chromium 브라우저

그래서 CSP가 그대로 적용됩니다.

자주 터지는 상황

9. 개발하면서 가장 많이 하는 착각

10. 개발자 현실 한 줄 요약

"경로 문제인 줄 알았는데 CSP였다"

⚠️ 헷갈리지 마세요 (CSP 2가지)

여기까지 읽으면서

혹시 이런 생각 드신 분 있을 수 있습니다.

“CSP? AWS 같은 그 CSP 말하는 건가?”

👉 아닙니다.

지금 이 글에서 말하는 CSP는 클라우드가 아니라 ‘보안 정책’입니다.

이 글에서의 CSP

🔐 Content Security Policy

default-src 'self';
img-src 'self' data:;

👉 브라우저(Electron 포함)가

어떤 리소스를 실행할 수 있는지 제한하는 보안 규칙

그런데 또 하나의 CSP가 있다

개발하다 보면 또 다른 CSP를 보게 됩니다.

Cloud Service Provider

• AWS
• Azure
• GCP

👉 서버, DB, 인프라 제공하는 클라우드 서비스

핵심 차이

마무리

CSP는 처음엔 굉장히 까다롭게 느껴집니다.

하지만 한 번 이해하면

👉 보안을 유지하면서 원하는 것만 허용할 수 있는 강력한 도구가 됩니다.

…네, 하반기 회고도 또 늦었습니다. 하하 😇 상반기 쓸 때만 해도 “이번엔 제때 써야지!” 했는데 역시나 현실은 늘 예상보다 빠르고, 저는 늘 예상보다 바빴습니다.

2025년 하반기도 마찬가지로,,, 솔직히 말하면 너무 정신없어서 시간이 어떻게 지나갔는지도 잘 기억이 안 날 정도였어요.

지난 상반기 회고록을 보실 분들은 여기루 ㅎㅎ 상반기 회고록 보기

근데 신기하게도, 막상 돌아보려고 하니까 머릿속에 제일 먼저 떠오른 단어는 이거였습니다.

테스트. 사용자. 구조. 그리고 책임.

상반기가 ‘처음’을 많이 겪은 시기였다면, 하반기는 그 처음들의 결과를 끝까지 책임지면서 진짜로 부딪힌 시간이었어요.

코드는 잘 짰다고 생각했는데 무너졌고, 설계는 괜찮다고 믿었는데 사용자 앞에서 깨졌고, 문서는 미뤄둔 만큼 되돌아와서 저를 괴롭혔습니다.

그리고 저는 그 모든 걸 배포하고, 고치고, 다시 확인하고, 또 배포하는 반복 속에서 조금 더 단단해졌던 것 같아요.

웃으면서 시작했지만 내용은 전혀 웃을 수 없었던(?) 2025년 하반기 이야기를 이제 하나씩 꺼내보려고 합니다.

그럼, 본격적으로 시작해볼게요.

🧨 7월 — 통합 테스트를 시작한 순간, 평화도 같이 종료되었다

7월은 제가 단위 테스트를 했다는 사실에 괜히 뿌듯해하던 나 자신을 가장 세게 반성한 달이었습니다.

5월에 단위 테스트를 도입했을 때는 솔직히 이런 마음이었어요.

“이 정도면 꽤 단단하지 않나?”

“적어도 큰 건 다 잡았겠지?”

지금 와서 말하자면,

그건 정말 순진한 착각이었습니다.

단위 테스트와 통합 테스트는 전혀 다른 이야기였다

7월에 본격적으로 통합 테스트 시나리오를 작성하고, 실제로 테스트를 돌리기 시작했어요.

그리고 거의 바로 깨달았습니다.

“아… 이건 단위 테스트랑 차원이 다르네.”

단위 테스트는

• 함수가 잘 도는지
• API 응답을 잘 처리하는지
• 특정 조건에서 에러가 나는지

를 보는 개발자 중심의 테스트였다면,

통합 테스트는

• 사용자가 처음 이 화면을 봤을 때 뭘 할지
• 어떤 버튼을 누를지
• 실수했을 때 어디서 막히는지

를 전부 보는 사람 중심의 테스트였어요.

그리고 이 ‘사람’은 개발자가 아니었습니다.

개발자가 쓴 통합 테스트 시나리오의 문제

처음엔 당연하게도 통합 테스트 시나리오를 개발자들이 직접 작성했어요.

결과요?

• 내부 상태를 이미 알고 있다는 전제
• “정상 케이스 기준”의 흐름
• 전문 용어가 자연스럽게 섞인 문장들

딱 보자마자 이런 생각이 들었습니다.

“이거… 개발 안 한 사람은 못 하겠는데?”

통합 테스트는 개발을 전혀 모르는 사람도 문서만 보고 그대로 따라 하면 테스트가 가능해야 했어요.

• 여기서 뭘 클릭해야 하는지
• 이 화면이 뜨는 게 정상인지
• 잘못했을 땐 어떤 메시지가 보여야 하는지

모든 걸 ‘사용자 언어’로 다시 써야 했습니다.

이 과정에서 처음 느꼈어요.

“사용자 입장에서 쓴다는 게

이렇게까지 어려운 일이었구나.”

그리고… 버그가 미친 듯이 튀어나오기 시작했다

통합 테스트를 본격적으로 돌리자, 그동안 잠잠하던 시스템이

마치 기다렸다는 듯이 무너지기 시작했습니다.

• 단위 테스트에선 한 번도 안 났던 버그
• 특정 순서에서만 터지는 문제
• 상태가 살짝만 어긋나도 바로 깨지는 흐름

그제야 깨달았어요.

“단위 테스트 때 수월했던 게 아니라,

그냥 그때는 안 보였던 거였구나.”

7월의 제 하루는 거의 이랬습니다.

배포한다

테스트한다

어, 또 터진다

고친다

다시 배포한다

다시 테스트한다

그리고 이 루틴을

하루에도 몇 번씩 반복했습니다.

퇴근하고 나면 아무것도 하고 싶지 않았고,

“오늘은 뭘 배웠지?”보다는

“오늘은 그래도 큰 사고는 없었다.”

이 문장으로 하루를 정리하던 날들이었어요.

배포–테스트–배포–테스트, 그리고 지연의 시작

이 반복이 계속되다 보니 자연스럽게 일정이 밀리기 시작했습니다.

처음엔 “오늘만 좀 더 보자”였고,

그 다음엔 “이번 주까지만 마무리하자”였고,

어느새 지연이 지연을 낳는 구조가 되어버렸어요.

이때 처음으로 통합 테스트의 진짜 무서움을 느꼈습니다.

통합 테스트는 문제를 ‘만들어내는’ 테스트가 아니라 문제를 ‘숨길 수 없게 만드는’ 테스트구나.

그리고 이 여파는 7월로 끝나지 않았습니다.

이 통합 테스트의 후폭풍은 8월까지 고스란히 이어지게 됩니다.

🧩 8월 — 통합 테스트의 후폭풍, 그리고 “이건 코드 문제가 아니었다”

7월이 통합 테스트의 시작이었다면,

8월은그 테스트가 남긴 후폭풍을 전부 떠안은 달이었습니다.

7월 말쯤에는 이런 희망 섞인 생각을 했어요.

“그래도 큰 건 다 나왔겠지…?”

“이제 좀 안정되겠지…?”

네.

역시나 틀렸습니다.

통합 테스트는 끝났지만, 문제는 이제 시작이었다

8월이 되자 통합 테스트에서 발견된 문제들이

하나씩 정리되는 게 아니라,

서로 엮이기 시작했습니다.

• 이 버그를 고치면 저쪽이 깨지고
• 이 흐름을 맞추면 다른 시나리오가 어긋나고
• 한 화면을 고치면 전체 동작이 미묘하게 변하고

이쯤 되니 머릿속에 계속 맴돌던 생각이 하나 있었어요.

“이거… 뭔가 이상한데?”

코드가 아니라, 구조가 문제라는 걸 깨닫다

처음엔 당연히

“로직을 더 꼼꼼히 보자” , “예외 처리를 추가하자”

이렇게 접근했습니다.

근데 아무리 봐도 문제는 코드 몇 줄이 아니었어요.

그때 처음으로 명확하게 느꼈습니다.

“이건 구조 문제다.”

• 흐름이 한눈에 안 보이고
• 상태가 여기저기 흩어져 있고
• 책임이 애매하게 나뉘어 있고
• 테스트 기준도 흔들리고 있고

결국

“왜 이런 문제가 반복되지?”라는 질문의 답은

“전체 구조를 제대로 그린 적이 없어서”

였습니다.

결국 시퀀스 다이어그램을 꺼내 들었다

사실 시퀀스 다이어그램은 원래 문서 설계 단계에서 했어야 하는 작업이었어요.

하지만 우리는 늘 그렇듯,

• “일단 개발부터”
• “시간 없으니까 나중에”
• “지금은 돌아가잖아”

이런 이유로 미뤄두고 있었죠.

그리고 8월이 되어서야 그 ‘나중에’가 찾아왔습니다.

시퀀스를 그리기 시작하자 비로소 보이기 시작했어요.

• 이 요청이 왜 여기로 가는지
• 이 상태가 왜 여기서 바뀌는지
• 이 타이밍에 이 로직이 왜 호출되는지

그리고 동시에 이런 생각도 들었습니다.

“아… 이걸 처음에 했으면

덜 고생했겠구나.”

구조 변경이라는 지옥문이 열리다

시퀀스를 정리하고 나니

선택지는 딱 두 개였습니다.

1. 지금 구조를 유지한 채 계속 땜질하면서 버틴다

2. 지금 아프더라도 구조를 다시 잡는다

결국 선택한 건 두 번째였습니다.

그리고 솔직히 말해서요.

구조 변경은 정말 미친 경험이었습니다.

• 어디까지 고쳐야 하는지 감이 안 오고
• 하나 고치면 다 고친 것 같고
• 근데 또 하나 안 고치면 전체가 흔들리고

이때는 진짜로

“다시는 구조 변경 안 하고 싶다…”

라는 말이 입 밖으로 몇 번이나 나왔어요.

문서를 미룬 대가를 몸으로 치르다

8월의 가장 큰 교훈은 기술적인 것보다 이거였습니다.

“문서는 귀찮아서 미루는 게 아니라, 나중에 나를 살리기 위해 쓰는 거다.”

문서를 제대로 정리하지 않은 상태에서의 개발은

• 기억에 의존하고
• 감에 의존하고
• “아마 이랬던 것 같아”로 움직이는 개발

이게 얼마나 위험한지 8월에 제대로 배웠습니다.

이때부터는 코드를 고치기 전에

• 흐름을 적고
• 조건을 정리하고
• 상태 변화를 글로 써보고

그 다음에야

코드를 손대기 시작했어요.

8월의 체감 난이도는 ‘멘탈’

7월이 체력 싸움이었다면, 8월은 멘탈 싸움이었습니다.

“이게 맞나?” “지금 방향이 맞는 걸까?” “괜히 더 망치고 있는 건 아닐까?”

이런 생각이 하루에도 몇 번씩 들었어요.

근데 아이러니하게도 그 와중에 느낀 게 하나 있었습니다.

“아… 나 지금

진짜 실무 개발하고 있구나.”

편한 선택이 아니라 맞는 선택을 하려고 고민하는 시간이었으니까요.

8월을 지나고 나서

제 개발 태도는 확실히 바뀌었습니다.

• “일단 고치자”보다 ** “왜 이렇게 됐지?”** 를 먼저 묻게 됐고

• 코드보다 흐름을 먼저 보게 됐고

• 문서를 귀찮은 게 아니라 필수 장비로 보게 됐어요.

그리고 무엇보다,

“통합 테스트는 끝이 아니라, 진짜 개발의 시작이다.”

라는 걸 이 달에 확실히 배웠습니다.

🧯 9월 — 사용자성이라는 벽, 그리고 “우리는 아무것도 몰랐다”

9월은 제가 개발자로 일하면서

가장 큰 충격을 받은 달이었습니다.

7–8월이 테스트와 구조의 지옥이었다면,

9월은 그 모든 걸 통과한 뒤에 만난

현실 사용자라는 보스 스테이지였어요.

시험성적서와 납품, 그리고 동시에 시작된 사용자성 개발

9월에 들어서자

일정표에 새로운 단어가 추가됐습니다.

시험성적서. 그리고 납품.

이 두 단어가 등장한 순간, 개발의 기준이 완전히 바뀌었어요.

이전까진 “기능이 된다”가 기준이었다면,

이제는

• 이걸 처음 보는 사람이 이해할 수 있는가
• 실수했을 때 당황하지 않는가
• 다시 시도할 수 있는가

이 질문들이 모든 기능 위에 올라탔습니다.

“개발자들끼리는 다 알잖아요?”

솔직히 말하면 저희는 이런 착각을 하고 있었어요.

“이 정도면 설명 안 해도 알겠지.”

“이건 개발자면 바로 이해하지 않나?”

근데 사용자 테스트를 돌리는 순간 그 착각은 바로 깨졌습니다.

사용자들은

• 어디서 시작해야 하는지 모르고
• 다음 단계가 뭔지 모르고
• 잘못 눌렀는지조차 몰랐어요

그걸 보면서 진짜로 멍해졌습니다.

“어… 이게 그렇게 어려워?”

사용자성은 ‘조금 다듬는 문제’가 아니었다

처음엔 라벨을 바꾸고, 툴팁을 달고,

설명을 한 줄 추가하면 될 줄 알았어요.

근데 아니었습니다.

문제는 훨씬 깊었습니다.

• 시작 지점이 모호했고
• 중간 단계가 많았고
• 실패했을 때의 길이 없었어요

그래서 결국 프로세스를 다시 만들기 시작했습니다.

한 번 만들고

돌려보고

다시 부수고

또 만들고…

이걸 거의

10번 가까이 반복했습니다ㅜㅜㅜㅜ

개발자에게 당연한 흐름은, 사용자에게 공포였다

9월에 가장 충격이었던 건 이거였어요.

개발자 기준으로는 “자연스러운 흐름”이,

사용자 기준에서는 “이거 잘못하면 큰일 나는 거 아냐?” 로 느껴진다는 사실.

보안 제품이라는 특성까지 겹치니

사용자 입장에서는

• 한 번의 실수가
• 시스템 전체에 영향을 줄 것처럼 느껴졌고
• 그래서 더 아무것도 못 하게 되더라구요

그때 처음으로 이해했습니다.

사용자성은 편의성이 아니라, 심리적 안전감이다.

구현보다 어려웠던 것: ‘안심시키는 설계’

이 시점에서

개발보다 더 어려웠던 건

• 어디까지 막아야 할지
• 어디까지 자유를 줄지
• 어디서 “괜찮아요”라고 말해줘야 할지

이 판단들이었습니다.

그래서 9월엔

• 한 단계씩 진행 상황을 보여주고
• 되돌릴 수 있다는 걸 명확히 하고
• 잘못된 선택은 미리 막고

사용자가 불안해하지 않게 만드는 것에

집중하게 됐어요.

야근과 주말 출근, 그리고 웃픈 현실

이 과정은 시간이 정말 많이 들었습니다.

9월에서 끝날 줄 알았던 작업은 10월까지 이어졌고,

야근은 자연스러워졌고 주말 출근도 생겼어요.

월급날 야근수당과 주말수당이 찍힌 금액을 보고

잠깐이나마 아 이게 내 진짜 월급이면 좋겠다....

라는 생각이 들었다는 겁니다.ㅎㅎ,,,,야근수당 최고,,,

(+ 웃픈 토스 보이스피싱,,,)

이렇게 사용자성 때문에 정신이 혼미해지던 와중에

갑자기 토스에서 문자가 하나 왔습니다.

순간 심장이 철렁해서

“혹시 상반기에 지원했던게,,,?” 했다가 확인해보니

그냥 보이스피싱이었습니다.

토스가 나한테 직접 연락할 리가 없잖아요…

잠깐 설렜던 나 자신 매우 반성합니다.

그리고 다시 현실로 복귀했습니다.

🏸 현실 도피가 아니라, 현실 불편 해결용 사이드

9월에 회사 프로젝트 때문에 머리가 계속 터지고 있던 와중에

웃기게도(?) 하나의 사이드 프로젝트를 만들게 됐습니다.

남자친구가 배드민턴 점수랑 득실차를

매번 수기로 계산하면서 너무 힘들어하길래

“아 그냥 내가 만들어줄게…” 하고

급하게 점수 계산 사이트를 하나 만들었어요.(사실 클로드 코드 썼어요,,,잘하더라고요,,)

솔직히 UI는 엉망이었고 사용자성도 좋다고 말하기는 어려웠지만,

적어도 이제 계산이 틀릴 일은 없다는 것 하나로

그 사이트는 존재 이유가 충분했습니다.

프로젝트 구경은,,,,,여기 클릭 나만보는 배드민턴 점수집계 +혹시 사용자성이나 의견 좀 주세여,,,,,ㅠ 인덱스 db만 썼습니다...

회사에선 사용자성을 고민하느라 미치고 있었는데

사이드에서도 결국 똑같이 “사람이 덜 힘들게 하는 게 개발이구나”를

또 한 번 느끼게 된 순간이었어요.

9월을 지나고 나서 저는 확실히 알게 됐어요.

• 사용자는 우리가 생각한 대로 행동하지 않는다
• 설명 없는 자유는 오히려 독이다
• 제품은 기능이 아니라, 신뢰로 평가된다

라는 걸요

10월 — 시험성적서, 구조 개편, 그리고 “그래도 내가 잘 가고 있구나”

10월은 제가 개발자로서

도망치던 것들과, 동시에 처음으로 보상받은 것들이 한꺼번에 밀려온 달이었습니다.

9월이 사용자성으로 멘탈을 흔들었다면,

10월은 기술적으로도, 감정적으로도

꽤 복합적인 달이었어요.

시험성적서가 등장한 순간, 개발의 기준이 바뀌었다

10월에 들어서자 일정표에 본격적으로 등장한 단어가 하나 있었습니다.

시험성적서.

이 네 글자가 등장하자마자

그동안 “괜찮겠지”로 넘어가던 모든 것들이

전부 질문으로 바뀌었어요.

• 이 기능은 정말 안정적인가?
• 에러가 나면 얼마나 빨리 캐치할 수 있는가?
• 성능 저하는 없는가?
• 이 동작을 문서로 설명할 수 있는가?

이제는 “개발자의 감”이 아니라

완성도와 근거로 증명해야 하는 단계였습니다.

완성도를 요구받는 순간, 구조의 민낯이 드러났다

시험성적서를 기준으로 하나하나 점검하다 보니 확실히 보였습니다.

폴더 구조가 너무 비효율적이었다는 것.

그동안은

• “여기서도 쓰고”
• “저기서도 쓰고”
• “이 파일이 이 역할도 하고, 저 역할도 하는”

상태였는데,

시험성적서 기준으로 보니까

• 수정 범위가 너무 넓고
• 에러 추적이 어렵고
• 테스트 기준도 모호해지고

결국 결론은 하나였습니다.

“역할 기반 구조로는 한계다.”

그래서 10월에

역할 기반 → 기능 기반 폴더 구조로 프론트엔드 구조를 아예 갈아엎었습니다.

이미 일정이 촉박한 상황에서

이 결정을 내린 건

솔직히 말해서 도박에 가까웠어요.

근데 동시에 이런 생각도 들었습니다.

“지금 안 바꾸면

이건 평생 고통이다.”

그래서 시간내서 빠르게 바뀌버렸습니다..

그리고 회의 중, 나를 찌른 한 순간

10월 즈음, 에러 원인을 찾기 위한 회의 중에

이야기가 자연스럽게

• 프로세스
• 스레드
• 내부 동작 구조

이쪽으로 흘러갔습니다.

그런데 그때 제가 이 흐름을

명확하게 설명하지 못하겠더라구요.

순간 머릿속이 하얘졌어요.

“나는 프론트엔드 개발자인데…”

“이건 나중에 공부해도 되지 않나?”

그동안 프론트엔드라는 이유로

OS, 프로세스, 스레드 같은 영역을

은근슬쩍 피해왔던 게

그 순간 그대로 드러났습니다.

부끄러웠어요. 진짜로.

“프론트엔드라서”라는 변명을 버리기로 했다

회의가 끝나고 혼자 앉아서 이런 생각이 들었습니다.

“이건 프론트 범위를 벗어난 문제가 아니라,

지금 내가 다루는 시스템의 일부잖아.”

그래서 그때부터 마음속에서 이 말을 지웠어요.

“나는 프론트엔드 개발자니까.”

대신 이렇게 바꿨습니다.

“나는 이 시스템을 만드는 개발자니까.”

완벽하진 않지만,

프로세스와 스레드, OS 기본 구조를 다시 공부하기 시작했고,

적어도

“왜 이런 문제가 터질 수 있는지”는

설명할 수 있어야겠다고 다짐했습니다.

그런데, 이 모든 와중에 찾아온 작은 보상

정신없이 구조를 바꾸고,

시험성적서를 준비하던 10월에

뜻밖의 연락 하나를 받았습니다.

코드잇 스프린트 커리어 프로그램 우수수료자 선정.

이력서 공개와 함께

짧은 인터뷰를 진행하게 됐고,

우수수료자로 뽑혔다는 이야기를 들었을 때

솔직히 기분이 정말 좋았습니다.

네이버 포인트 5만 원도 받았고요. (이건 중요합니다 😄)

하지만 그보다 더 좋았던 건,

현직 대기업 개발자분이 제 포트폴리오와 이력서를 보고 “잘했다”고 평가해줬다는 사실이었어요.

“아… 나, 방향은 맞구나”

10월은 계속해서 부족함을 느끼고,

자존심도 많이 흔들렸던 달이었는데,

이 작은 인정 하나가 제 마음을 꽤 단단하게 잡아줬습니다.

“아, 내가 완벽하진 않아도

헛되게 가고 있는 건 아니구나.”

그래서 그때 처음으로

이런 생각이 들었어요.

“앞으로도 그냥, 꾸준히만 하자.”

조급해하지 말고,

비교하지 말고,

지금처럼 계속 쌓아가면 된다고.

10월은

힘들고, 아프고, 많이 반성했던 달이었지만

동시에 처음으로 ‘외부에서의 인정’을 받은 달이기도 했습니다.

• 구조의 중요성을 몸으로 배웠고
• “프론트엔드라서”라는 변명을 내려놓았고
• 그리고, 내가 잘 가고 있다는 신호도 받았습니다.

그래서 10월을 한 문장으로 정리하자면 이거예요.

“아직 부족하지만, 그래도 계속 가도 되겠다고 느낀 달.”

🧪11월 — 시제품 이후, 그리고 “제품은 개발자 뜻대로 쓰이지 않는다”

11월은 제가 처음으로

‘이제 이건 팔만한 제품용이 아니다.’라는 말을

몸으로 실감한 달이었습니다.

10월까지는 “그래도 아직 내부용이지” “시연 단계니까 괜찮겠지”

라는 마음이 아주 조금은 남아 있었는데,

11월에 들어서면서 그 여지는 완전히 사라졌어요.

시제품 다음 단계는, 생각보다 훨씬 어려웠다

11월부터는 명확하게 기준이 바뀌었습니다.

“이건 나중에 시장에 나가도 되는 기능인가?”

이 질문이 모든 개발의 출발점이 됐어요.

그리고 솔직히 말하면,

시제품보다 이 단계가 훨씬 더 어려웠습니다.

시제품 단계에서는 조금 불편해도, 조금 투박해도,

“컨셉은 보여줬잖아”로 넘어갈 수 있었거든요.

근데 제품은 아니었습니다.

• 한 번 더 눌러야 하는 버튼
• 헷갈리는 용어 하나
• 설명 없는 화면 전환

이 모든 게

바로 ‘문제’가 됐어요.

기술 시연, 그리고 예상 못 한 장면들

11월에는 인천으로 기술 시연도 진행했습니다.

이 시연에서 제가 가장 크게 충격받은 장면이 하나 있어요.

그냥, 정말 그냥

‘닫기 버튼’을 하나 추가해준 기능이 있었거든요.

개발자 입장에서는 “있으면 편하겠지” 정도의 버튼이었는데,

사용자는 그 버튼을 눌러서

아예 다음 단계를 진행하지 않고 그대로 종료해버렸습니다.

그 장면을 보는 순간

머릿속이 잠깐 멈췄어요.

“어… 아니… 그게 그 용도가 아닌데…”

사용자는 항상 ‘가장 쉬운 탈출구’를 찾는다

그 시연을 계기로 확실히 깨달은 게 있습니다.

사용자는 우리가 의도한 흐름을 따르지 않는다.사용자는 가장 쉬운 길을 선택한다.

개발자 입장에서는 “이건 중간에 나가면 안 되는 단계”였지만,

사용자 입장에서는 “지금 안 해도 되는 것”이었던 거죠.

이걸 보고 나서

선택지에 대한 기준이 완전히 바뀌었습니다.

• 정말 필요한 선택인가?
• 사용자가 도망가도 괜찮은 지점인가?
• 아니면 반드시 안내하고 붙잡아야 하는 단계인가?

이걸 하나하나 다시 정의하기 시작했어요.

자유는 안내 없이는 독이 된다

11월에 가장 크게 바뀐 제 생각은 이거였습니다.

“사용자에게 선택지를 많이 주는 게 항상 좋은 건 아니다.”

우리는 “선택이 많으면 좋겠지”라고 생각했지만,

실제 사용자는 선택이 많을수록 더 불안해했습니다.

특히 보안 제품이라는 특성 때문에

사용자 입장에서는

• 한 번의 실수가
• 큰 문제로 이어질 것처럼 느껴졌고
• 그래서 아예 아무것도 안 하게 되는 경우도 많았어요.

그때 깨달았습니다.

사용자성은 편의성이 아니라, ‘안심시키는 설계’라는 걸요.

11월이 남긴 가장 큰 깨달음

11월을 지나고 나서 제 머릿속에 남은 문장은 이거였습니다.

“제품은 개발자가 만드는 게 아니라, 사용자가 완성한다.”

아무리 구조가 좋아도, 아무리 코드가 깔끔해도,

사용자가 이해하지 못하면 그건 아직 제품이 아니었습니다.

11월은 이 사실을 가장 정직하게 마주한 달이었어요.

🔐 12월 — 안정성, 로그, 그리고 “사용자보다 먼저 고치는 사람”

12월은 화려하지 않았고, 눈에 띄는 새 기능도 많지 않았지만,

지금 돌이켜보면

하반기에서 가장 중요한 걸 만든 달이었습니다.

11월까지 사용자성과 제품의 무게를 배웠다면,

12월은 그걸 ‘지속 가능한 상태’로 만드는 달이었어요.

보안기능 인증시험, 그리고 현실의 시작

12월의 시작은 보안기능 인증시험 준비였습니다.

이건 단순히 “기능이 있다”를 증명하는 시험이 아니었어요.

• 실제 환경에서도 안정적인지
• 예상 못 한 상황에서도 버티는지
• 문제가 생기면 추적 가능한지

이걸 전부 보여줘야 했습니다.

그리고 이 과정에서 그동안 모르고 지나쳤던 사실 하나를 뒤늦게 알게 됐어요.

OS가 다르면, 에러도 다르다

이미 나간 기능들에서 OS별로 전혀 다른 에러가 발생하고 있다는 걸

12월에 와서야 명확하게 인지했습니다.

그게 정말 무서웠던 이유는 이거였어요.

에러는 있었는데, 우리는 그걸 모르고 있었다.

사용자는 그냥 “뭔가 이상한데?” 하고 넘어가거나,

아예 말을 안 했을 수도 있고,

우리는 “잘 돌아가겠지”라고 생각하고 있었던 거죠.

이걸 깨달은 순간, 등골이 살짝 서늘해졌습니다.

로그가 없으면, 아무것도 아니다

그래서 방향을 완전히 바꿨습니다.

12월의 키워드는 로그였습니다.

• 모든 에러를 파일로 남기고
• 그 로그를 자동으로 서버로 수집하고
• 원격에서 바로 확인할 수 있도록

에러를 ‘기록되지 않는 사고’가 아니라

‘관리 가능한 이벤트’로 바꾸는 작업이었어요.

Redis를 도입해서

에러 상태를 빠르게 확인할 수 있게 만들었고,

이제는

• 언제
• 어떤 환경에서
• 어떤 에러가
• 어떤 흐름에서 났는지

를 한 번에 볼 수 있는 구조를 만들었습니다.

안정성이란, 에러가 없는 상태가 아니었다

12월을 지나며 제가 완전히 바뀐 생각이 하나 있습니다.

이전엔 “안정적이다”라는 말을

에러가 없는 상태라고 생각했어요.

근데 아니었습니다.

안정성이란 에러를 빨리 알아차리고, 빨리 고칠 수 있는 상태였습니다.

이미 자동 업데이트 기능을 넣어둔 덕분에,

• 에러를 발견하고
• 수정하고
• 사용자 개입 없이 배포하는 흐름을

꽤 빠르게 만들 수 있었어요.

그때 처음으로 이런 생각이 들었습니다.

“아… 이 정도면

그래도 사용자한테 미안하지는 않다.”

그리고, 정말 오랜만에 나를 위한 개발

12월 내내 회사 일에 치여 살다 보니

사이드 프로젝트는 거의 손도 못 댔는데,

연말에 딱 하나 꺼낸 게 있었습니다.

3D 크리스마스 트리.

three.js로 만들었고, GPU를 살살 녹이면서

불빛이 반짝이는 트리를 만들었어요.

이 프로젝트는 완성도를 따지기보단,

“아, 나 아직 개발 좋아하네.”

이 감정을

다시 확인하기 위한 작업이었습니다.

사실 이 시점엔 체력도, 멘탈도 꽤 바닥이었어요.

그래도 전구가 반짝이는 걸 보면서

• 내가 만든 게 눈앞에서 움직이고
• 코드가 실제 화면이 되고
• ‘재밌다’는 감정이 다시 올라오는 순간

그게 참 좋았습니다.

개발을 좋아해서 시작했는데,

중간에 그 이유를 잠깐 잊고 있었구나 싶었어요.

크리스마스 트리 구경하러가기 3D 크리스 마스 트리 회고록 보러가기

🌙 2025년 하반기를 닫으며

2025년 하반기는

솔직히 말해서 정말 많이 무너지고, 많이 지치고, 많이 배웠던 시간이었습니다.

단위 테스트로 안심했던 코드들은 통합 테스트에서 깨졌고,

구조를 미뤄둔 대가는 일정과 멘탈로 돌아왔고,

“개발자끼리는 알겠지”라고 만든 기능들은 사용자 앞에서 전부 멈췄습니다.

그 과정 속에서 저는

코드를 잘 짜는 개발자가 아니라

끝까지 책임지는 개발자가 되어가고 있었다는 걸

뒤늦게 깨닫게 된 것 같아요.

혼자 야근하면서 좌절하던 순간도 많았지만,

회사 분들의 응원과 믿음,

특히 상사분들이 늘 이뻐해주시고 격려해주신 덕분에

끝까지 버틸 수 있었습니다.

그래서 이 하반기는

힘들었던 기억보다도

“그래도 나는 계속 가고 있구나”라는 감정으로 남아 있습니다.

Electron을 통해

웹 밖의 세계를 처음 경험했고,

솔루션과 시스템을 만드는 재미를 알게 되었고,

그래서 더 넓은 개발 영역에도 욕심이 생겼습니다.

2026년에는

three.js를 제대로 공부해보고 싶고,

vue.js도 깊게 다뤄보고 싶고,

언젠가는 로봇과 같은 하드웨어와 맞닿은 개발에도 도전해보고 싶습니다.

아직은 부족한 게 너무 많지만,

올해를 지나며 확실히 느낀 건 하나예요.

개발자는 무너지면서 자라고,

버틴 만큼 결국 다음 단계로 나아간다.

그래서 저는 내년에도

겁먹지 않고, 미루지 않고,

계속 배우고 실험하면서 나아가 보려고 합니다.

프론트엔드 개발자 송연지,

2026년에도 성장 중으로 살아가겠습니다. 🚀💙

마지막으로 이 긴 하반기 회고를

여기까지 읽어주신 분들께 진심으로 감사드립니다.

저는 여전히 느리고, 부족하고,

남들보다 돌아가고 있다는 느낌을 받을 때도 많지만

그래도 올해를 지나면서 한 가지는 확실히 믿게 됐어요.

속도는 늦을 수 있어도

방향만큼은 맞는 개발자로 가고 싶다.

빠르게 성장하는 개발자도 멋있지만,

저는 실수하더라도 배우고,

무너지더라도 기록하고,

결국엔 단단해지는 개발자가 되고 싶습니다.

혹시 이 글을 읽고 있는 누군가도

지금 느리다고 느껴지거나, 비교 때문에 힘들다면

우리 그냥 이렇게 말했으면 좋겠어요.

“늦어도 괜찮다. 멈추지만 않으면 된다.”

개발자는 결국

계속 배우는 사람이 이긴다고 저는 믿습니다.

그래서 저는 내년에도 계속 배우고, 도전하고, 버틸 거고

이 글을 읽는 모든 개발자 분들도

각자의 자리에서 원하는 방향으로 끝까지 나아가시길

진심으로 응원합니다.

우리 모두 2026년도 화이팅입니다. 🚀💙!

크리스마스가 오면 사람들은 트리를 꺼내고,

개발자는 콘솔을 켭니다.

그리고 이렇게 생각합니다.

“별 찍고 공백 맞추는 트리…

나도 한 번쯤은 만들어봤지.”

    *
   ***
  *****
 *******
*********

이 트리의 문제점은 명확합니다.

재미가 없습니다.

너무 빨리 끝납니다.

그리고 GPU가 전혀 아프지 않습니다.

그래서 문제가 됩니다.

🎅 이 정도로는 만족하지 못합니다

문득 이런 생각이 들었습니다.

“three.js를 아직 안 써봤는데

이걸 크리스마스까지 미루면 영영 안 쓰는 거 아닐까?”

공부 목적으로 시작하기엔 귀찮고,

사이드 프로젝트로 하기엔 애매한데

마침 트리가 있었습니다.

그래서 결론은 간단했습니다.

트리를 3D로 만들자. 느리면 느린 대로 두자.

🌲 그래서 나온 결과물

👉 https://3-d-christmas-tree.vercel.app/

• 마우스로 돌릴 수 있고
• 전구가 깜빡이고
• 눈이 내리고
• 설정 패널까지 있습니다

그리고 제일 중요한 특징 하나.

컴퓨터가 크리스마스를 함께 느낍니다. (팬 소리)

🧩 기술 얘기

이번 트리는

Next.js 위에 React Three Fiber를 얹어서 만들었습니다.

three.js를 직접 쓰기엔 연말이었고,

그래서 React스럽게:

• group으로 장식들을 묶고
• useFrame으로 전부 움직이게 만들고
• 전구는 배열로 쭉 만들었습니다

전구 깜빡임은 사실 굉장히 단순합니다.

Math.sin(time + offset)

하지만 이 한 줄 덕분에

전구들이 “나 각자 살아있다”는 태도를 보입니다.

🎛️ 괜히 만들어본 설정 패널

전구 개수, 속도, 눈 내림 여부, 자동 회전.

없어도 되는데

있으면 더 만지고 싶어집니다.

이걸 만들면서 느낀 점은 하나였습니다.

설정 패널은 기능보다

괜히 있는 게 더 중요하다.

🐢 최적화는요? 안 했습니다

왜냐하면

이 트리는 실무용이 아니라

연말 감성용이기 때문입니다.

• 전구 많음
• 라이트 많음
• 눈 계속 떨어짐

그래서:

• 노트북이 따뜻해지고
• 팬이 돌고
• 크리스마스 분위기는 최고입니다

🎄 성능을 희생하여 연말을 얻었습니다.

🎁 이 프로젝트의 진짜 목적

이 트리는

잘 만든 트리가 아닙니다.

하지만:

• 만들면서 재밌었고
• three.js를 “써봤다”는 기록이 남았고
• 내년에 또 트리를 만들 핑계가 생겼습니다

그럼 이걸로 충분하지 않겠습니까.

✨ 마무리

개발자라면

별 한 번 찍고

공백 한 번 맞추고

결국엔 트리를 만들어야 합니다.

올해는 콘솔이 아니라

GPU로 만들었을 뿐입니다.

메리 크리스마스입니다 🎄 그리고 개발자 여러분, 트리는 늘 옳습니다.

— 비동기 때문에 흔들리던 UI를 React가 직접 통제하기 시작한 순간

프론트엔드 개발을 하다 보면 자연스럽게 하나의 고민이 생깁니다.

“왜 로딩 UI가 이렇게 많지?”

“왜 페이지 이동할 때 깜빡이지?”

“데이터 패칭 실패하면 화면이 바로 죽는 이유가 뭘까?”

“컴포넌트마다 isLoading, error를 계속 만들어야 하는 게 맞는 걸까?”

React는 분명 “UI를 선언적으로 그리는 라이브러리”인데,

정작 데이터 패칭·로딩·에러·코드 스플리팅처럼 실제 애플리케이션에 반드시 필요한 비동기 흐름은 React가 직접 관리하지 않았습니다.

그 결과 애플리케이션 구조는 점점 복잡해졌습니다.

• 로딩 UI가 곳곳에 흩어지고
• 에러 처리 방식은 개발자마다 다르고
• 코드 스플리팅은 가능하지만 “대기 UI”는 직접 만들어야 하고
• 렌더링 중 깜빡임(Flash)이 생기고
• 데이터가 늦게 도착하면 빈 화면이 잠깐 노출되고…

React 팀은 어느 순간 이렇게 결론을 내립니다.

“비동기는 UI의 일부이므로, UI 프레임워크인 React가 이걸 직접 통제해야 한다.”

그 결론의 첫 번째 산물이 바로 Suspense입니다.

그리고 나머지 기술들은 이 Suspense라는 개념을 중심으로 확장된 애들입니다.

이 글에서는 기술 이름만 나열하지 않고,

• ✔ 왜 등장했는지 (발생 배경)
• ✔ 어떤 구조적 문제를 해결했는지 (개념)
• ✔ 내부적으로 어떻게 작동하는지 (메커니즘)
• ✔ 언제 쓰는지 (사용 시점 예시)

이 네 가지 축으로 길게 정리해보겠습니다.

1. 🎯 React의 근본적 한계: “UI는 동기적이다”라는 오래된 가정

React는 초기에 “상태 → UI”라는 동기적 렌더링 모델을 기반으로 설계됐습니다.

즉, 렌더링 시점에는 모든 데이터가 이미 존재한다고 가정한 거죠.

하지만 실제 애플리케이션은 다음처럼 비동기 투성이입니다.

• API에서 데이터 가져오기
• Lazy 로딩된 컴포넌트 불러오기
• 사용자 인터랙션에 따른 추가 데이터 조회
• SSR/CSR 간 데이터 교환
• 리소스 로딩(이미지, 폰트, 스크립트 등)

이 비동기 흐름을 React는 “외부 상태”나 “사용자 정의 로직”으로 해결하게 만들었습니다.

그 때문에 애플리케이션 구조는 자연스럽게 이렇게 변해갔습니다.

• ❌ 컴포넌트마다 isLoading, error를 도배
• ❌ 데이터 도착 전 UI가 잠깐 깨져 보임
• ❌ 코드 스플리팅했는데 로딩 UI는 직접 구현
• ❌ 에러 발생 시 화면 전체가 죽어버림
• ❌ 렌더링이 비동기로 인해 뒤틀리는 현상(깜빡임, 빈 화면)

이건 React의 “버그”라기보다는,

애초에 React가 비동기를 렌더링 모델 안에 포함시키지 않았기 때문입니다.

그러니 React는 이런 질문을 하게 됩니다.

“비동기를 UI 렌더링의 일부로 만들 수 없을까?”

Suspense는 바로 그 질문에 대한 첫 번째 대답입니다.

2. 🍱 React.lazy — 코드 스플리팅을 “React의 비동기”로 만들다

2-1. 코드 스플리팅의 등장 배경

프론트엔드 앱이 커지면서 JS 번들은 점점 커졌고,

SPA 특성상 안 쓰는 페이지 JS까지 처음에 다 들고 오는 문제가 생겼습니다.

그래서 Webpack / Vite 같은 도구가 코드 스플리팅을 제공하기 시작했죠.

하지만 이 상태에서는 이런 문제가 남아 있었습니다.

“번들은 쪼개지는데, 그게 로딩 중인지 아닌지 React는 모른 척한다.”

그래서 예전에는 이런 코드가 많았습니다.

// (예전에 흔히 보던 패턴 – 직접 상태 관리)
function LazySettingsWrapper() {
  const [Settings, setSettings] = React.useState<React.ComponentType | null>(null);

  React.useEffect(() => {
    import('./Settings').then(mod => {
      setSettings(() => mod.default);
    });
  }, []);

  if (!Settings) {
    return <div>설정 화면 불러오는 중...</div>;
  }

  return <Settings />;
}

• 모듈 로딩 상태를 직접 관리해야 하고
• 로딩 UI도 매번 직접 짜야 하고
• 에러 처리도 따로 해야 합니다.

React는 이걸 “React가 직접 지원해야 하는 영역”이라고 보고,

React.lazy를 도입합니다.

const Settings = React.lazy(() => import('./Settings'));

이 한 줄은 단순히 “동적 import”가 아닙니다.

내부적으로는 렌더링 중에 Promise를 던지는 컴포넌트가 됩니다.

즉, 렌더링 중에 이 컴포넌트를 만나면 흐름이 이렇게 바뀝니다.

렌더링 → Promise throw → “대기 필요”

근데 아직 React는 이 Promise를 받을 줄 모릅니다.

이 Promise를 받아서, “잠깐 이 UI 대신 다른 걸 보여주자”를 처리해주는 애가 바로 Suspense입니다.

2-2. React.lazy + Suspense 기본 사용 예시

import React, { Suspense } from 'react';

const SettingsPage = React.lazy(() => import('./SettingsPage'));

export function App() {
  return (
    <Suspense fallback={<div>설정 화면 불러오는 중...</div>}>
      <SettingsPage />
    </Suspense>
  );
}

• SettingsPage는 아직 안 받아온 상태일 수 있고
• 그 동안 Suspense가 fallback을 렌더링해줍니다.

여기서 이미 “비동기 로딩을 UI 렌더링의 일부로 넣는다”는 개념이 시작됩니다.

3. 🎬 Suspense — 렌더링 중 비동기 “대기”를 정식 기능으로 넣은 기술

Suspense를 잘 모르면 흔히 이렇게 생각하기 쉽습니다.

“아, 로딩 스피너 보여주는 컴포넌트지?”

절반은 맞고, 절반은 틀렸습니다.

Suspense의 본질은 “렌더링 중 발생한 비동기를 React가 직접 처리하는 것”입니다.

3-1. Suspense는 DOM을 어떻게 다룰까?

중요한 포인트는 이겁니다.

Suspense는 DOM을 직접 조작하지 않고,

“렌더링 과정을 제어”합니다.

대략적인 흐름은 이렇습니다.

1. Suspense 아래에 있는 컴포넌트가 Promise를 던짐
   • 예) React.lazy, React Query suspense: true, 커스텀 리소스 래퍼 등
2. React는 지금 진행 중인 렌더링을 중단함
3. 가장 가까운 Suspense Boundary를 찾음
4. 그 Boundary에 정의된 fallback UI를 대신 렌더링
5. Promise가 resolve되면
   • React가 다시 원래 렌더링을 이어서 수행
   • 기존 fallback DOM은 사라지고, 실제 UI로 자연스럽게 교체

즉, “fallback → 실제 UI”로 부드럽게 전환되는 전체 과정을

React 렌더링 엔진이 직접 관리하게 됩니다.

3-2. Suspense를 쓸 때 체감되는 효과

이 방식 덕분에:

• 로딩 상태가 컴포넌트 깊은 곳에 흩어지지 않고
• “어디까지를 하나의 로딩 단위로 볼 건지”*를 Boundary로 명확하게 자를 수 있고
• 화면이 깜빡이거나, 잠깐 빈 영역이 보이는 문제를 줄일 수 있습니다.

예를 들어 이런 식입니다.

// 대시보드 전체를 하나의 Suspense boundary로 감싸는 예시
function Dashboard() {
  return (
    <Suspense fallback={<div>대시보드 로딩 중...</div>}>
      <UserSummary />   {/* 내부에서 데이터 패칭 */}
      <ActivityChart /> {/* 내부에서 데이터 패칭 */}
      <NotificationList /> {/* 내부에서 데이터 패칭 */}
    </Suspense>
  );
}

각 컴포넌트가 알아서 비동기를 던지고,

Suspense가 그 전체를 하나의 “로딩 화면”으로 묶어줍니다.

좀 더 세분화하고 싶다면, 이런 식도 가능합니다.

function Dashboard() {
  return (
    <div>
      <Suspense fallback={<div>프로필 불러오는 중...</div>}>
        <UserSummary />
      </Suspense>

      <Suspense fallback={<div>활동 차트 로딩 중...</div>}>
        <ActivityChart />
      </Suspense>
    </div>
  );
}

Boundary를 어떻게 나눌지에 따라

“사용자가 어디까지를 하나의 화면으로 인식할지”를 설계할 수 있습니다.

4. 🛡 ErrorBoundary — Suspense와 100% 맞물려 돌아가는 에러 복구 메커니즘

여기까지 보면 Suspense는 “대기(loading)”만 해결합니다.

그러면 “실패(error)”는 누가 처리할까요?

대답: Suspense가 아니라, ErrorBoundary입니다.

4-1. ErrorBoundary의 동작 흐름

React는 렌더링 중 에러가 발생하면 아래와 같이 동작합니다.

1. 렌더링 중 Error가 throw됨
2. React는 렌더링을 중단
3. 가장 가까운 <ErrorBoundary>를 찾음
4. 그 Boundary의 fallback UI를 렌더링하여 안전하게 복구

Suspense = “기다림” 담당

ErrorBoundary = “실패” 담당

둘이 세트라고 보면 됩니다.

4-2. ErrorBoundary 예시

// 클래스형 컴포넌트로만 공식 지원
class RootErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean }
> {
  constructor(props: any) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError() {
    return { hasError: true };
  }

  componentDidCatch(error: any, info: any) {
    console.error('[ErrorBoundary]', error, info);
  }

  render() {
    if (this.state.hasError) {
      return <div>문제가 발생했습니다. 잠시 후 다시 시도해 주세요.</div>;
    }
    return this.props.children;
  }
}

// Suspense와 함께 사용
function App() {
  return (
    <RootErrorBoundary>
      <Suspense fallback={<div>전체 앱 로딩 중...</div>}>
        <MainRouter />
      </Suspense>
    </RootErrorBoundary>
  );
}

• 비동기 로딩 중에는 Suspense가 처리
• 비동기 실패(또는 동기 에러)는 ErrorBoundary가 처리

이렇게 되면:

• API 하나 터졌다고 전체 앱이 흰 화면이 되는 걸 막을 수 있고
• “특정 영역만 에러 UI로 교체” 같은 UX를 설계할 수 있습니다.

5. 🔗 React Query + Suspense — 데이터 패칭을 React 렌더링 모델에 완전히 편입

React Query를 쓸 때 가장 익숙한 패턴은 이거일 겁니다.

const { data, isLoading, isError } = useQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
});

if (isLoading) return <div>로딩 중...</div>;
if (isError) return <div>에러…</div>;

이 방식의 단점은:

• 컴포넌트마다 로딩/에러 조건문이 반복되고
• 로딩 UI가 페이지 전역에서 제각각 만들어지고
• 중첩 컴포넌트 구조에서는 가독성이 급격히 떨어진다는 점입니다.

React 18 이후, React Query는 suspense: true를 지원하면서 완전히 다른 그림이 나옵니다.

// React Query + Suspense 사용
const { data } = useQuery({
  queryKey: ['user', userId],
  queryFn: fetchUser,
  suspense: true,  // 핵심
});

이제 내부적으로는 이렇게 동작합니다.

• 로딩 중 → Promise를 던짐 → Suspense에서 fallback 렌더
• 실패 → Error를 던짐 → ErrorBoundary에서 복구
• 성공 → 정상적으로 데이터 사용

예시를 한 번에 정리하면:

function UserProfile() {
  const { data: user } = useQuery({
    queryKey: ['user', 1],
    queryFn: fetchUser,
    suspense: true,
  });

  return <div>{user.name}님 안녕하세요.</div>;
}

function App() {
  return (
    <RootErrorBoundary>
      <Suspense fallback={<div>사용자 정보를 불러오는 중입니다...</div>}>
        <UserProfile />
      </Suspense>
    </RootErrorBoundary>
  );
}

여기서 포인트는:

• UserProfile 내부에는 isLoading, isError가 사라지고
• 로딩/에러 처리는 “위에서 한 번에” 잡아줄 수 있다는 점입니다.

실제 프로젝트가 커지면, 이 구조가 생각보다 엄청 시원해집니다.

6. 🌊 Server Components + Streaming — Suspense가 만들어낸 SSR 진화

Next.js 13 이후 도입된 Server Components / Streaming도 사실 Suspense 위에 서 있는 기능입니다.

아이디어는 단순합니다.

“서버에서 준비된 부분만 먼저 보내고,

아직 안 된 부분은 Suspense fallback으로 대체해서 보낸 다음,

준비되면 해당 부분만 교체하자.”

6-1. 아주 간단한 예시 느낌

// app/page.tsx (Next.js 13+ 예시 느낌)
import { Suspense } from 'react';
import UserFeed from './UserFeed';

export default function Page() {
  return (
    <><h1>대시보드</h1>
      <Suspense fallback={<div>피드 로딩 중...</div>}>
        {/* 서버에서 데이터 패칭 후 스트리밍 */}
        <UserFeed />
      </Suspense>
    </>
  );
}

실제로는 서버가:

1. <h1>대시보드</h1>와 fallback을 먼저 내려보내고
2. UserFeed 데이터가 준비되면
3. 해당 영역만 치환하는 방식으로 동작합니다.

이 구조 덕분에:

• 초기 렌더링 체감 속도가 빨라지고
• 네트워크 지연이 덜 답답해지고
• JS 번들 크기도 줄어들고
• UX가 훨씬 자연스러워집니다.

이 모든 게 가능한 이유가 바로 “부분적으로 UI를 대체하고 다시 복구한다”는 Suspense 모델이 존재하기 때문입니다.

7. 🎛 결국 이 기술들은 하나의 흐름이다

정리해보면:

즉, 이 기술들은 따로 떨어진 기능 목록이 아니라

“React 렌더링 모델의 진화 과정에서 등장한 한 계보”에 가깝습니다.

공통된 철학은 항상 하나입니다.

“UI와 비동기를, React가 직접 통제하겠다.”

8. 🌱 Suspense를 제대로 쓰기 위한 사전 조건

Suspense는 강력하지만, “그냥 아무 데나 막 꽂아 넣으면 좋은 기능”은 아닙니다.

개인적으로는 아래 같은 상황에서 특히 잘 맞는다고 느꼈습니다.

• ✔ 비동기 로직이 컴포넌트 곳곳에 섞여 있을 때
• ✔ 로딩/에러 UI를 일관되게 관리하고 싶을 때
• ✔ 페이지/기능 단위 코드 스플리팅을 적용하고 싶을 때
• ✔ 여러 API를 병렬로 호출하면서도 깔끔한 UI 흐름을 만들고 싶을 때
• ✔ Next.js처럼 SSR/Streaming까지 염두에 둔 구조를 만들고 싶을 때

이럴 때 “Suspense + ErrorBoundary + (React Query or lazy)” 조합이 진짜 빛을 발합니다.

🎉 마지막 요약

Suspense는 “로딩 스피너 보여주는 컴포넌트”가 아닙니다.

Suspense는 React가 비동기 UI 전체를 스스로 통제하기 시작한 첫 번째 기술입니다.

비동기 → 대기 → 복구 → 렌더링

이 전체 사이클을 React 내부 엔진이 책임지는 구조로 바꾸면서,

• 깜빡임 없는 UI
• 일관된 로딩/에러 처리
• 코드 스플리팅의 자연스러운 적용
• SSR Streaming 같은 차세대 기능

이런 것들이 한 줄로 이어지기 시작했습니다.

개인적으로는,

“Suspense를 이해하는 순간

‘React 생태계 전체가 왜 이런 방향으로 진화하고 있는지’가

훨씬 명확하게 보인다”

라는 느낌이 들었습니다.

— 다시 빌드하기 싫을 때 꼭 필요한 꿀팁입니다

Electron 개발을 하다 보면, 이런 순간이 꼭 찾아옵니다.

개발 모드에서는 정말 말 잘 듣던 앱이

배포 모드(Prod)만 올라가면 갑자기 태도가 달라지는 순간이요.

• 무한 로딩만 뱅글뱅글 돈다든지
• 특정 페이지에서 멈춘다든지
• 엔진 IPC만 Prod에서 실패한다든지
• 심지어 콘솔도 안 찍혀서 뭐가 문제인지 감도 안 잡히는…

게다가 더 난감한 건,

“아… 제가 DevTools를 막아놨죠…”

이겁니다.

보안을 위해 devTools: false 넣어놨거나

빌드할 때 콘솔 제거 플러그인까지 적용해놓아서

배포된 exe에서는 DevTools를 열 수 없는 상황이 됩니다.

이때, 보통 떠올리는 해결책은 두 가지입니다.

1. DevTools 다시 열리게 코드 고치고 →
2. 빌드 → 패키징 → 설치 → 다시 테스트

하지만…

솔직히 이 과정, 한 번 하면 괜찮은데

버그가 계속 바뀌기라도 하면 정말 피곤해집니다.

그래서 저는 결국 방법을 찾아냈습니다.

✨ 결론부터 말하자면,

배포된 exe 그대로 DevTools를 열 수 있습니다.

다시 빌드하지 않아도 됩니다.

코드를 한 줄도 고칠 필요 없습니다.

심지어 devTools를 false로 막아놔도 가능합니다.

Electron의 정체는 결국 Chromium 기반 브라우저입니다.

그리고 Chrome에는 공식적으로 “원격 디버깅 포트(Remote Debugging Port)”라는 기능이 있습니다.

이걸 Electron에서도 그대로 활용할 수 있습니다.

즉, 앱을 실행할 때 아래 옵션 한 줄만 붙이면 됩니다.

--remote-debugging-port=9222

이게 끝입니다.

🔧 방법: 배포된 exe에서 DevTools 강제로 열기

1. CMD(명령 프롬프트)를 실행합니다.

윈도우키 → cmd → 엔터

2. 배포된 exe가 있는 폴더로 이동합니다.

예를 들어 앱이 여기 설치돼 있다고 가정하면:

C:\Users\사용자명\AppData\Local\Programs\YourApp

명령어는:

cd "C:\Users\사용자명\AppData\Local\Programs\YourApp"

3. 앱을 디버깅 포트와 함께 실행합니다.

YourApp.exe --remote-debugging-port=9222

이렇게 실행한 순간부터 Electron 내부의 Chromium은

디버깅용 포트(9222)를 열어놓게 됩니다.

앱은 그대로 정상 실행됩니다.

코드도 건드린 적 없습니다.

하지만 Chromium은 “디버깅 연결 준비 완료” 상태가 됩니다.

4. Chrome 브라우저에서 DevTools로 접속합니다.

Chrome 주소창에 입력합니다:

chrome://inspect

→ “Discover network targets” 클릭

→ localhost:9222 추가

→ 아래쪽 “Remote Target”에 Electron 프로세스가 뜹니다.

→ Inspect 버튼을 클릭합니다.

그러면 바로 DevTools가 열립니다.

Elements, Console, Network, Sources, Performance, Application…

배포 모드에서만 보이는 그 문제들을

그 자리에서 그대로 확인할 수 있습니다.

🎁 이 방법의 장점

✔ devTools: false여도 무조건 열립니다

Electron 옵션으로 막혀 있어도 상관없습니다.

✔ 콘솔 제거 플러그인 적용돼 있어도 Network/Elements는 완전히 보입니다

remove-console 같은 플러그인 적용돼도 콘솔만 사라질 뿐,

디버깅 포트 연결은 그대로 가능합니다.

✔ asar로 압축된 배포 버전에서도 당연히 가능합니다

app.asar이든 unpacked든 관계 없습니다.

✔ 다시 빌드할 필요가 없습니다

코드 수정 → 빌드 → 패키징 → 설치…

이 반복 루프를 피할 수 있습니다.

✔ 생산성 급상승

Prod 환경에서만 터지는 버그를 바로 캐치할 수 있습니다.

💬 마무리

Electron을 쓰다 보면 “개발 모드에서는 안 나는 버그가 왜 배포 모드에서만…” 이런 상황이 흔합니다.

그럴 때 DevTools까지 막혀 있다면 디버깅 자체가 막히기 쉽죠.

하지만 Electron은 브라우저 기반이기 때문에

이렇게 디버깅 포트만 열어주면 언제든 다시 DevTools를 연결할 수 있습니다.

저는 이 기능을 알고 난 후로

배포 빌드 다시 만드는 일이 절반으로 줄었습니다.

똑같은 문제를 겪고 있는 분들께 꼭 도움이 되었으면 합니다.

API 요청 로그가 두 번씩 찍히는 현상을 경험하신 적 있으신가요?

저도 Electron + React 기반 사내 프로젝트를 하다가,

“어? 내 코드가 잘못된 건가? 서버가 중복 응답을 주는 건가?” 하고 한참을 헤맸습니다.

결론부터 말씀드리면, 이건 React StrictMode 때문입니다.

제 삽질 경험을 토대로, 왜 이런 일이 일어나는지, 배포에서는 어떤지,

그리고 제가 얻은 교훈까지 정리해보겠습니다.

1. StrictMode란 무엇인가요?

React의 StrictMode는 개발 모드에서만 실행되는 검증 도구입니다.

• 코드에서 안전하지 않은 패턴을 찾고,
• 메모리 누수 가능성이 있는 코드를 조기에 발견하고,
• 사이드 이펙트(side effect) 실행 과정을 검증하기 위해

React가 일부러 컴포넌트를 더 빡세게 실행합니다.

왜 API 요청도 두 번 갈까?

StrictMode는 단순히 렌더링만 두 번 하는 게 아니라,

useEffect 같은 부작용(side effect) 코드도 마운트 → 클린업 → 다시 마운트 흐름으로 반복 실행합니다.

즉, 코드가 이렇게 생겼다면:

useEffect(() => {
  fetchApi(); // API 호출
}, []);

실행 순서는 이렇습니다:

1. 첫 번째 마운트 → fetchApi() 실행 → API 요청 1회
2. 언마운트 & 클린업
3. 두 번째 마운트 → 다시 fetchApi() 실행 → API 요청 1회

👉 결과적으로 API 요청이 2번 전송됩니다.

즉, 내 코드에는 문제가 없고, React가 일부러 그렇게 하는 겁니다.

개발 모드 vs 배포 모드

• 개발 모드 (npm run start / vite dev 등)

  StrictMode가 활성화되어 API 요청이 두 번 갑니다.

• 배포 모드 (npm run build 후 실행, electron-builder 배포 등)

  StrictMode 자체가 제거됩니다. 따라서 API는 정상적으로 한 번만 호출됩니다.

저도 electron-builder로 패키징해서 실행했을 때는,

로그에 요청이 한 번만 찍히는 걸 확인했습니다.

개발할 땐 두 번, 배포하면 한 번 → 이게 정상입니다.

2. 중복 호출을 막는 방법

개발 모드에서 로그가 두 번 찍히는 게 불편하다면,

간단히 useRef를 써서 가드를 걸 수 있습니다.

const hasFetchedRef = useRef(false);

useEffect(() => {
  if (hasFetchedRef.current) return;
  hasFetchedRef.current = true;

  fetchApi();
}, []);

이렇게 하면 개발 모드에서도 API는 한 번만 호출됩니다.

저는 보통, 조회 API는 두 번 호출돼도 상관없으니 그냥 두고,

중복 호출이 문제가 되는 등록/수정/승인 API만 이런 방어 로직을 넣었습니다.

페이지 클릭 시 조회 API 호출

Electron 프로젝트에서는 페이지 이동(라우터 클릭)마다 조회 API가 다시 호출되는데,

여기에 StrictMode까지 더해지니 “응답이 두 개씩 오는 것처럼” 보여서 헷갈리더군요.

실제로 로그는 이렇게 찍힙니다:

[API ▶ getCpnMember 요청] { cpnId: 2, userId: 2 }
[API ◀ getCpnMember 응답] { result: { pscd: 'OK', data: [], pcsRsltMsg: '응답을 보냈습니다.' } }
[API ◀ getCpnMember 응답] { result: { pscd: 'OK', data: [], pcsRsltMsg: '응답을 보냈습니다.' } }

처음엔 “응답이 두 번 오네?”라고 생각했지만, 사실은 요청을 두 번 보낸 거였어요.

이것도 StrictMode의 영향으로, 배포 모드에선 정상적으로 한 번만 호출됩니다.

다만 페이지 이동 시마다 조회 API가 자동으로 불리는 구조라면,

캐시나 상태 관리 도구를 붙여서 불필요한 호출을 줄이는 게 좋습니다.

3. React Query / SWR 같은 라이브러리 쓰기

이런 문제를 더 깔끔하게 해결하고 싶다면,

React Query나 SWR 같은 데이터 관리 라이브러리를 추천드립니다.

• 같은 API를 여러 페이지에서 불러도 캐시에서 가져오기
• 새로고침 버튼을 눌렀을 때만 refetch 실행
• 상태/에러/로딩을 한 줄로 관리

저는 단순 조회 API는 React Query로 관리하고,

트랜잭션성(등록/삭제/승인) API만 직접 호출하도록 나누니 훨씬 편했습니다.

React Query / SWR이 해결해주는 방식

React Query와 SWR은 단순히 API 호출 라이브러리가 아니라, 데이터 캐싱 계층이에요.

이 캐싱 계층이 있으면 “같은 키(key)”로 요청이 들어올 때 다음과 같은 일이 일어납니다:

1. 디듀플리케이션(Deduplication)

   • 동일한 API 요청이 짧은 시간 안에 여러 번 발생하더라도,

     내부에서 “아 이건 같은 요청이네”라고 판단하고 한 번만 실제로 요청을 보냅니다.

   • 나머지는 캐시된 결과나 동일 Promise를 공유.

2. 캐싱(Cache)

   • 한 번 받아온 데이터를 캐시에 저장하고,

     동일한 키로 다시 조회하면 네트워크 요청 없이 즉시 캐시 데이터 반환.

   • refetch() 같은 명령을 내리면 그때만 새로 요청.

3. 상태 관리 자동화

   • 로딩(isLoading), 성공(data), 에러(error) 상태를 자동으로 관리해 줘서,

     개발자가 직접 loading state 만들고, try/catch 돌릴 필요가 없어져요.

구체적인 예시

// React Query 예시
const { data, isLoading, error } = useQuery(
  ['member', cpnId, userId], // 키
  () => getCpnMember({ cpnId, userId }) // API 호출
);

위 코드를 StrictMode 환경에서 두 번 실행한다고 가정해봅시다:

• 일반 fetch 사용: 요청 2번 → 서버에도 2번 요청

• React Query 사용: 요청은 2번 트리거되더라도,

  내부에서 동일 키(['member', 2, 2])로 관리 → 실제 네트워크는 1번만 발생

  두 번째 호출은 첫 번째 호출의 캐시/Promise를 재활용합니다.

SWR은 어떻게 다르냐?

SWR도 원리는 비슷한데, 차이점은 “자동 새로고침”과 “Stale-While-Revalidate” 전략이 강점이에요.

• React Query: 좀 더 완전한 데이터 관리 플랫폼 (mutate, optimistic update 등 풍부)
• SWR: 단순 조회 중심, 사용법이 직관적이고 lightweight

그래서 왜 좋은가?

개발 모드에서 StrictMode 때문에 네트워크 요청이 2번씩 찍히는 상황에서도:

• 일반 fetch → 서버에 실제로 2번 요청 감

• React Query / SWR → 서버엔 한 번만 요청 감

  (개발자 입장에서는 로그만 2번 찍히고, 실제 요청은 캐시가 막아줌)

게다가 캐시·상태 관리까지 자동이니,

“개발 모드라 로그가 번잡해도 실제 서버 트래픽은 안정적으로 1회”라는 안심을 줍니다.

👉 React Query / SWR은 StrictMode 환경에서 API 중복 호출을 막아주는 안전장치 + 상태 관리 자동화 기능을 제공하기 때문에, “로그가 두 번 찍히는 게 헷갈려요”라는 문제와 “불필요한 서버 트래픽” 문제를 동시에 해결해줍니다.

제가 얻은 교훈

1. 개발 모드에서 API가 두 번 호출되는 건 StrictMode의 정상 동작이다.
2. 배포 모드에서는 정상적으로 한 번만 호출되니 걱정할 필요 없다.
3. 불편하다면 useRef 가드로 중복 호출을 막을 수 있다.
4. 페이지 이동 시마다 조회 API를 다시 호출하는 구조는 필요에 따라 최적화해야 한다.
5. React Query / SWR 같은 라이브러리를 쓰면 중복 호출 문제를 훨씬 깔끔하게 관리할 수 있다.

저는 이 삽질을 통해, 이제는 API 로그가 두 번 찍혀도 당황하지 않습니다.

“아, StrictMode 때문이지~” 하고 바로 넘길 수 있게 되었죠. 😎

혹시 여러분도 비슷한 경험 있으신가요?

만약 API 로그가 두 번 찍힌다면, 이제 안심하셔도 됩니다.

여러분의 코드가 잘못된 게 아니라, React가 일부러 그런 거니까요!

Electron + Vite로 개발하면서 VM 환경에서 패키징을 하다 보면,

“같은 코드, 같은 설정인데 엔진이 안 열린다”는 이상한 상황을 겪는 경우가 있습니다.

처음에는 단순한 VM(가상머신) 속도 문제겠거니 하고 넘어갔지만,

문제는 하루이틀이 아니라 빌드할 때마다 가끔 꼭 나타난다는 점이었죠.

더 이상한 건, 아무것도 바꾸지 않고 다시 빌드하면 또 잘 된다는 것이었습니다.

이쯤 되면 운이 좋은 건지, 빌드가 장난을 치는 건지 알 수 없었습니다.

💡 빌드 산출물과 캐시의 숨겨진 함정

빌드를 하면 dist/, release/, build/ 같은 폴더에 실행 파일과 번들된 JS가 생성됩니다.

이게 바로 빌드 산출물입니다.

문제는 이 폴더에 남아 있는 예전 파일이 다음 빌드에 그대로 섞여 들어갈 수 있다는 점입니다.

여기에 캐시(Cache)까지 더해집니다.

Vite, Webpack, Next.js 등 빌드 도구들은 빌드를 빠르게 하기 위해 캐시를 사용합니다.

변경이 없는 파일은 다시 처리하지 않고 재활용하죠.

하지만 가끔 변경 감지를 놓치면, 오래된 결과물이 그대로 살아남아 버립니다.

캐시는 빌드 속도를 높이는 ‘부스터’이지만, 잘못 쓰이면 발목을 잡는 ‘지뢰’가 되기도 합니다.

🗂 빌드 도구별로 지워야 할 폴더

프로젝트마다 지워야 할 폴더가 다릅니다.

아래 표는 대표적인 빌드 환경에서 청소해야 할 캐시와 빌드 산출물 폴더입니다.

🧹 클린 빌드의 발견

이때부터 “클린 빌드(Clean Build)”라는 개념을 깊이 들여다봤습니다.

클린 빌드는 이전 빌드 산출물과 캐시를 완전히 지우고, 깨끗한 상태에서 새로 빌드하는 과정입니다.

문제의 근본 원인은 단순했습니다.

이전 빌드의 잔여 파일과 캐시가 새 빌드에 섞여 들어가면서

파일 누락, 변경 미반영 같은 기이한 현상을 만든 것이었습니다.

🛠 클린 빌드 실행 방법

수동 삭제

# macOS / Linux
rm -rf dist release out build .vite .webpack-cache node_modules/.cache

# Windows PowerShell
rd /s /q dist release out build .vite .webpack-cache node_modules\.cache

npm 스크립트 자동화

"scripts": {
  "clean": "rimraf dist release out build .vite .webpack-cache node_modules/.cache",
  "build": "npm run clean && electron-builder"
}

rimraf 설치:

npm i rimraf --save-dev

📦 Electron + 엔진 exe 포함 시 주의할 점

Electron 앱에서 엔진 실행 파일을 같이 배포하려면,

electron-builder의 extraResources에 정확한 경로를 지정해야 합니다.

"build": {
  "asar": true,
  "asarUnpack": [],
  "extraResources": [
    { "from": "electron/engine/bin/seph_engine.exe", "to": "public/seph_engine.exe" }
  ],
  "files": [
    "dist/**",
    "electron/**",
    "!**/*.map"
  ]
}

경로를 명확히 해주면 패키징 시 엔진 파일 누락을 방지할 수 있습니다.

🔄 CI/CD 환경에서의 클린 빌드

GitHub Actions, Jenkins, GitLab CI 같은 CI/CD 서버는 매번 깨끗한 환경에서 빌드하지만,

빌드 속도를 높이려고 캐시를 켜면 이 문제가 다시 생길 수 있습니다.

GitHub Actions 예시

steps:
  - name: Clean build
    run: rm -rf dist release .vite .webpack-cache node_modules/.cache
  - name: Install dependencies
    run: npm ci
  - name: Build
    run: npm run build

⚠️ VM 환경에서 자주 발생하는 변수

• I/O 속도 지연 → 파일 복사나 압축이 중간에 누락될 수 있음
• 스냅샷 복원 → 예전 빌드 결과물이 그대로 복귀
• 시간 동기화 문제 → 설치기가 파일 변경을 인식 못 함
• 백신 간섭 → 실행 파일을 격리 또는 삭제

🛡 엔진 실행 전 점검 코드

import fs from 'fs';
import path from 'path';
import { spawn } from 'child_process';

const enginePath = path.join(process.resourcesPath, 'app.asar.unpacked', 'public', 'seph_engine.exe');

function fileExists(p: string) {
  try { return fs.existsSync(p); } catch { return false; }
}

export function startEngine() {
  if (!fileExists(enginePath)) {
    throw new Error(`[Engine Missing] ${enginePath}`);
  }

  const proc = spawn(enginePath, [], { detached: true });
  proc.on('error', (err) => {
    console.error('[Engine Spawn Error]', err);
  });
}

✅ 빌드 실패 원인 체크리스트

• 이전 빌드 결과물을 삭제했는가?
• 캐시 폴더를 비웠는가?
• 앱 버전을 올렸는가?
• 엔진 exe 경로가 정확한가?
• 실행 권한이 있는가?
• 백신에서 차단하지 않았는가?

📍 마무리

클린 빌드는 특정 빌드 도구 전용 기능이 아니라, 모든 개발 환경에서 통하는 안전장치입니다.

캐시는 빌드 시간을 단축시키는 좋은 도구지만, 잘못 쓰이면 발목을 잡는 주범이 되죠.

특히 VM 환경에서는

클린 빌드 + 버전 증가 + 경로 고정

이 세 가지가 빌드 안정성의 핵심입니다.

저도 예전에는 “안 되면 한 번 더 빌드하지 뭐”라고 생각했지만,

이제는 처음부터 깨끗하게 빌드해서 한 번에 성공하는 습관을 들였습니다.

빌드 환경도 집처럼, 주기적인 대청소가 필요합니다.

프론트엔드 개발자라면 누구나 한 번쯤 console.log("확인")을 찍어본 경험이 있을 겁니다. 저도 그랬습니다.

디버깅의 든든한 친구, 언제 어디서나 호출하면 나타나는 log 친구.

하지만 Electron 프로젝트에선 이 친구가 성능 병목의 주범이 될 수도 있습니다.

💻 Electron 환경의 로그, 왜 특별한가요?

Electron은 두 개의 프로세스로 구성됩니다:

✅ 문제는 여기서 시작됩니다

이 둘은 로그를 찍는 방식도, 로그가 시스템에 미치는 영향도 다릅니다.

• Renderer 로그 (console.log)
  • 브라우저 콘솔처럼 작동
  • 많이 찍히면 렌더링 지연, 메모리 누수 가능
  • 개발자 도구를 통해 사용자가 직접 볼 수 있음
  • 무한 루프나 interval 로그가 많을 경우 UI에 영향
• Main 로그 (console.log)
  • Node.js의 stdout으로 출력
  • 로그가 많아지면 디스크 IO 병목, 프로세스 지연, 리소스 누수 가능
  • 특히 보안 솔루션이나 데몬처럼 작동하는 앱일수록, 안정성이 중요

결국, 단순히 “로그 좀 많네” 수준이 아니라 시스템 성능 저하, 사용자 불편, 심지어 보안 이슈로도 이어질 수 있는 구조입니다.

🚨 실전에서 겪은 문제

제가 참여한 보안 솔루션 기반 Electron 프로젝트에서는 다음과 같은 로그들이 지속적으로 발생했습니다:

• Named Pipe 통신 로깅
• 시스템 정보 수집 로그
• JSON 저장/파싱 로깅
• 보안 상태 체크 및 사용자 행동 로그

초당 수십 개의 로그가 찍히다 보니:

• 렌더러 메모리가 지속적으로 증가하거나
• CPU 사용량이 6~8% 이상 고정되거나
• 통신이 비동기적으로 지연되거나
• 개발자 도구를 비활성화했음에도 내부 자원 누수 발생

이런 증상이 실제로 있었습니다.

😅 안일했던 생각: "어차피 배포용은 devtool 막았잖아?"

Electron에선 개발자 도구를 막을 수 있으니, log가 사용자에게 노출되지 않는다고 생각했습니다.

그래서 귀찮아서 수백 줄의 console.log를 안 지웠습니다. 😔

하지만…

console.log("✅ 요청 성공", response);
console.log("📍 현재 상태", status);
console.log("🚨 예외 발생", error)

이런 로그가 계속 쌓이면, 렌더링 지연, 메모리 누수, 디스크 I/O 부하로 이어지는 걸 실제로 경험했습니다.

🦸 구원자 등장 — vite-plugin-remove-console

수동으로 일일이 삭제하는 건 너무 비효율적이었고, 구글링 도중 발견한 라이브러리가 바로 이 구원자입니다.

📦 설치 및 설정

npm i vite-plugin-remove-console -D

// vite.config.ts
import removeConsole from 'vite-plugin-remove-console';

export default defineConfig({
  plugins: [
    react(),
    removeConsole({
      include: ['**/*.ts', '**/*.tsx'],
    }),
  ],
});

✅ 효과

• console.log, console.debug, console.info → 빌드시 자동 제거
• 개발 모드에서는 기존 코드 그대로 유지
• 실수로 배포에 디버깅 로그가 포함될 위험 방지
• Renderer 성능 저하 예방 (특히 많은 로그를 찍는 페이지에서 효과 큼)

+ 관련 라이브러리 비교

✅ 하지만 로그는 필요합니다 — electron-log

Renderer에서는 console.log를 지우지만, Main Process에서는 로그를 반드시 남겨야 합니다.

왜냐고요? Electron 앱의 핵심 기능은 대부분 Main에서 처리되기 때문입니다.

제가 맡은 프로젝트만 해도:

• Named Pipe를 통한 보안 엔진 통신
• 시스템 정보를 수집하고 상태를 기록하는 모니터링 루프
• 정책 초기화, 설정 로딩, 사용자 상태 갱신 등

모든 주요 흐름은 Main에서 일어납니다.

이때 오류가 발생하거나 예상치 못한 상황이 생기면 반드시 로그가 남아 있어야 디버깅이 가능하죠.

그래서 저는 Main에서는 console.log 대신 electron-log를 사용하고 있습니다.

💾 electron-log 기본 사용법

// main.ts
import log from 'electron-log';

log.info("📡 엔진 초기화 시작");
log.warn("⚠️ 중요한 설정 누락됨");
log.error("❌ 오류 발생", error);

🔍 Main 로그를 electron-log로 남기는 이유~!

📂 로그 경로는 여기에 파일로 저장됩니다.

🆚 로그 전략 비교 요약

🏁 결론: 로그도 설계 대상입니다

console.log는 디버깅에 아주 유용하지만, Electron처럼 리소스와 I/O에 민감한 환경에서는 설계 대상이 됩니다.

🧠 로그를 지우는 것이 중요한 게 아니라,

"어떤 로그를 언제, 어디에, 어떻게 남길 것인가" 가 중요합니다.

💬 마무리하며

Electron 기반 앱에서의 로그는 단순한 디버깅 도구가 아니라,

운영 효율성과 사용자 경험을 좌우하는 요소가 됩니다.

지우지 않아도 되는 콘솔 로그?

어쩌면, 그게 병목의 시작일 수 있습니다.

저처럼 "귀찮아서 로그 안 지웠던 그때"의 저를 반성하며…

지금은 자동화된 안전한 로그 전략으로 한층 더 성장한 기분입니다.

정신없이 달리다 보니 벌써 2025년 반이 지나갔네요.

지난 6개월은 정말 제 커리어에서 다이내믹하고 가장 진심이 담긴 시기였어요.

• 처음으로 프로젝트를 리딩했고,

• 처음으로 데스크탑 앱을 만들었고,

• 처음으로 스스로 부족함을 느끼며 공부하고 기록했죠.

그럼, 진심 가득 담아 제 상반기 회고를 써 내려가 볼게요.

🧶 1월 — "생각하는 개발자"로 다시 태어난 순간들

작년 11월 중순, 저는 첫 개발 회사를 퇴사를 선택했습니다.

뭔가 막연한 두려움도 있었고,

“앞으로 뭘 하지?” 하는 허탈함도 있었지만, 마음 한구석에선 뚜렷한 갈망이 있었습니다.

“제대로, 성장하고 싶다.”

그렇게 시작한 게 코드잇 단기심화 6기였어요.

“단기”라는 말이 붙었지만, 그 6주는 제겐 커리어 전체를 재정비하는 6주였습니다.

FitMon 프로젝트 — 실력은 여기서 자라납니다

그 첫 시작은 팀 프로젝트 FitMon이었습니다.

“운동 + 모임 + 일정관리”를 연결하는 헬스케어 웹앱이었고,

그런데 단순히 구현만 하는 게 아니라,

진짜 전반적인 프론트 구조를 갈아엎는 경험을 했어요.

• 역할 기반 → 기능 기반 폴더 구조 전환
• API 응답 객체 기준 설계
• UX 흐름을 고려한 폼 컴포넌트 재사용
• Lighthouse 퍼포먼스 최적화
• eslint/prettier 통일
• 테스트 코드 작성

그리고 무엇보다 처음으로 멘토링을 받았습니다.

멘토님의 피드백은 솔직히 말하면... 좀 무섭기도 했어요.

“이런 구조는 유지보수가 어렵겠죠?”,

“이 부분, 왜 이렇게 작성했는지 설명해보세요.”

그런데 그 무서움 속에서 제가 진짜 성장하고 있다는 걸 느낄 수 있었어요.

'질문이 두려웠지만, 성장하고 있었다'

처음엔 질문하는 것도 어려웠습니다.

"이거 너무 기본적인 질문 아닌가?"

"내가 왜 이걸 모르지?"

이런 생각이 수시로 들었거든요.

그런데 용기 내서 질문하고,

피드백을 기록하고 적용하는 걸 반복하다 보니

정말 시야가 넓어졌습니다.

“기능 구현을 넘어, 생각하는 개발자가 되어간다.”

이걸 처음으로 체감한 순간들이었어요.

그리고... 시간은 남고, 리팩토링은 시작되었다

사실 저희 프로젝트는 꽤 일찍 완성됐습니다.

그래서 남은 기간엔 오롯이 리팩토링과 구조 개선에 집중할 수 있었어요.

코드의 응집도를 높이고,

비즈니스 로직과 UI 분리를 연습하고,

컴포넌트 재사용과 분리 기준도 고민했죠.

또한

정말 좋은 동료 개발자 친구들을 만난 것도 큰 수확이었습니다.

서로 코드리뷰하고, 에러 공유하고,

밤 늦게까지 디버깅하며 생긴 유대감은 아직도 기억에 남아요.

이때의 회고는 여기 👉

FitMon 프로젝트 및 코드잇 단기심화 회고

🚀 2월 — 발표, 입사, 해커톤, 진짜 미쳤던 한 달

1월의 고요하고 밀도 높은 성장기가 끝나자,

2월은 정말 말 그대로 폭풍처럼 몰아쳤습니다.

FitMon 발표 — 준비는 마쳤고, 자랑할 시간

2월 초엔 FitMon 프로젝트의 발표와 정리 과정을 마무리했습니다.

그동안 정리한 구조와 코드, 성능 최적화 포인트들을

발표 자료로 만들고 정리하면서

“아, 이 프로젝트는 정말 자랑할 수 있겠다”는 자신감이 생겼어요.

프로젝트를 남에게 설명할 수 있다는 건

그걸 충분히 이해했다는 뜻이잖아요?

그게 제겐 작지만 확실한 자존감 회복이었어요.

2월 17일, 첫 출근 — 이제부터는 진짜 실전이다

그리고 드디어 2월 17일,

보안 솔루션 회사에 첫 출근을 했습니다.

사실 입사 전까지만 해도

“내가 괜찮은 회사에 가는 게 맞을까?”

“기술적으로 도태되진 않았을까?”

이런 고민들이 있었지만,

첫 출근날 느꼈어요.

“아, 여기서도 나는 계속 배울 수 있겠구나.”

Electron 기반의 프로젝트,

보안 도메인이라는 낯선 분야,

내가 해보지 않은 구조들…

“할 게 너무 많다 = 재밌겠다.”

그게 제 첫 느낌이었습니다.

그런데 동시에... 엘리스 해커톤도 붙어버렸다

네… 맞아요…

이 타이밍에 엘리스 AI Spark Camp 해커톤도 붙어버렸습니다 😅

주제는 생성형 AI였고,

제가 제안한 아이디어인

“블로그 URL만 넣으면 영상 자동 생성”이 채택됐습니다.

그래서 퇴근하고 밤 11시까지는

AI 프로젝트를 개발,

주말엔 팀 회의와 테스트,

출근하면 보안 솔루션 개발…

숨 쉴 틈이 없었습니다.

그런데 이상하죠?

힘든데도 불구하고,

정말 너무 재밌었습니다.

최우수상, 그리고 자동화의 맛

그 프로젝트에서

저는 처음으로 Vercel, GitHub Actions를 연동해서

자동화 배포를 경험했고,

프롬프트 기반 영상 API 설계에도 참여하면서

AI와 프론트의 만남을 직접 체험할 수 있었습니다.

리팩토링을 못 한 건 아쉽지만,

그래도 최우수상이라는 결과로 마무리되면서

“이 미친 일정, 정말 보람 있었구나” 싶었어요.

AI Spark Camp 해커톤 회고 보기 엘리스 AI-Spark-Camp 해커톤 회고록

요약하면…

2월은 한 마디로 정리하면 이랬습니다.

“정신은 없었지만, 진짜 내가 살아있다는 느낌이 났다.”

코드잇에서 쌓은 자신감으로 현업에 뛰어들었고,

퇴근 후에는 창의성과 열정을 쏟아부었고,

그 와중에 좋은 동료와 멘토를 만나며 성장했습니다.

💻 3월 — Electron 입문과 현실 기획, 그리고 “이게 진짜 개발자의 일인가요…?”

3월은 제게 있어

“이게 실무구나”를 처음으로 체감한 한 달이었습니다.

그 전 직장은 체계나 이런것들이 부족해서 몰랐거든요. 이번 회사에서Electron 프로젝트에 본격 투입된 건 좋았는데,

그 안에서 제가 맡게 된 일은 단순한 기능 개발이 아니었어요.

Next.js 미지원? 라우팅 직접 구성하세요~

Electron을 처음 접했을 땐

“오 신기하다, 데스크탑 앱이야!” 하며 설렜지만

금방 현실이 저를 때렸습니다.

“Electron은 Next.js 안 돼요.”

😇 …?

라우팅 자동화도 없고,

스크롤 위치도 수동으로 초기화해야 하고,

상태 공유도 직접 구성해야 했습니다.

그래서 라우터는 react-router-dom으로 구성하고,

레이아웃도 직접 갈라야 했고,

페이지마다 사이드바 유무, 알림 유무, 접근 권한 여부 등을 직접 조건부로 걸어야 했죠.

진짜 귀찮았지만,

그래도 “이게 프론트엔드 기본기다”라고 생각하면서 배워나갔습니다.

근데 그보다 더 힘들었던 건… 문서였습니다

이때부터 제가 처음으로 실무 문서를 직접 작성하게 됐습니다.

그냥 요구사항 적는 수준이 아니라

진짜 ‘기획자처럼’ 정리하는 문서들이었어요.

• 사용자 정의서:

  이 기능은 누가 언제 어떤 조건에서 사용할 수 있는지,

  경고 메시지는 어떻게 뜨는지, 동작 흐름은 어떻게 되는지를 하나하나 정리

• 사용자 인터페이스 설계서 (UI 설계서):

  버튼 하나, 드롭다운 하나의 상태 변화까지 전부 작성.

  빈 화면일 때는 어떻게 표시되는지, 경고 배너는 언제 나타나는지 등

• 메뉴 구조 리스트:

  전체 앱의 좌측 사이드바 구조를 트리 형태로 정리하고,

  접근 권한별로 보이는/안 보이는 메뉴 구분

• 알림 정의서:

  어떤 이벤트에 어떤 메시지가, 어떤 타이밍에 어떤 위치에서 떠야 하는지를 일일이 명시

• 프로그램 명세서:

  어떤 파일이 어떤 기능을 담당하고,

  내부 API 호출 흐름은 어떻게 되며,

  로그는 어디에 저장되는지까지 다 작성

처음에는 진짜 멘붕이었습니다.

“개발자가 코드를 안 짜고 왜 이런 걸 쓰고 있지…?”

그런데 문서를 쓰면서 시야가 확장됐다

하지만 이상하게도

하루 이틀 쓰다 보니 어느 순간 느꼈습니다.

“이 문서들 덕분에 내가 지금 프로젝트 전체를 이해하고 있구나.”

단순히 기능을 ‘어떻게’ 구현하는지를 넘어서,

왜 이 기능이 필요한지,

어떤 예외 케이스를 고려해야 하는지,

내가 만든 코드가 누구에게 어떤 영향을 주는지를

정확히 고민하게 되었어요.

그리고 이런 문서들이 QA, 백엔드, 다른 개발자들과의 소통을 위한 진짜 도구라는 걸 처음으로 깨달았습니다.

“내가 코드만 잘 짜면 되는 줄 알았는데…”

이전까지는 솔직히

코드만 잘 짜면 된다고 생각했어요.

근데 3월을 지나고 나니까

코드는 말의 일부일 뿐이라는 걸 체감했어요.

• 문서를 통해 스펙을 설계하고
• 회의를 통해 기획을 조율하고
• 기록을 통해 협업을 유지하고
• 구현을 통해 책임을 완성하는 것

이게 진짜 실무 개발자의 흐름이라는 걸요.

주말엔 나만의 Electron 공부 시간

그래서 주중엔 문서, 회의, 조율…

그리고 주말엔 나만의 개발 시간이었습니다.

• main.ts, preload.ts의 구조
• contextBridge 통한 IPC API 연결
• 트레이 아이콘 추가
• 자동 실행 등록
• .exe로 배포하는 과정까지

주말마다 하나씩 실험하면서

진짜 “내가 데스크탑 앱을 만들고 있다”는 자각이 들었어요.

솔직히 꽤 짜릿했습니다. 😎

요약하자면...

3월은 “개발자는 코딩만 하지 않는다”는 걸,

그리고 “문서도 코드다”라는 걸

몸으로 배운 한 달이었습니다.

덕분에 이제는 문서 작성에도 자신감이 생겼고,

사람들과 기능을 논의할 때

기획-개발-디자인-사용자 전반을 고려하는 시야가 생겼습니다. 사실 이때 사람들이 개발 할 시간 없다 없다 하는걸 이해했습니다. 하하…

🏫 4월 — 9년 차 용역 개발자를 리딩하다니, 내가 이걸 진짜 해내네?

4월의 키워드는 단연 ‘용역관리’였습니다.

그냥 개발자 역할을 수행하던 제가,

처음으로 누군가를 관리하고 리딩하는 입장이 된 거죠.

게다가 상대는... 무려 9년 차 개발자였습니다. 😳

“제가 이걸 맡아야 하나요…?”

솔직히 처음엔 너무 부담스러웠어요.

“내가 잘못된 피드백을 주면 어쩌지?”

“말투가 날카로워 보이면 실례 아닐까?”

이런 생각이 머릿속에서 빙글빙글 돌았습니다.

하지만 시간이 지날수록 점점 명확해졌어요.

• 개발 연차와 실무 감각은 별개다
• 기술적으로 리딩이 필요한 건 사실이다
• 그리고 지금 내가 이끌지 않으면 프로젝트가 안 굴러간다

그래서 저는 용기를 내기로 했고,

문서 하나하나 작성하면서

전체 흐름을 정리하고,

할 일들을 일간/주간 단위로 쪼개서 공유하고,

그분께 코드 리뷰도 조심스럽게 요청하기 시작했어요.

물론 처음엔 어색했지만,

그분이 정말 너무 착하고 열린 분이라서 다행히 잘 풀려나갔어요.

기술보다 더 어려운 것: 사람과의 거리

이 일을 하면서 깨달은 건

“리딩은 기술보다 소통이 훨씬 어렵다”는 점이었어요.

실제로 제가 코드를 손대는 시간보다,

할 일을 정의하고, 맞는 방향으로 유도하고, 감정을 조율하는 시간이 더 많았거든요.

특히 제가 맡은 프로젝트는 단순한 페이지 개발이 아니라,

보안 정책과 시스템 흐름, 관리 기능을 통합한 중간 규모 프로젝트였기 때문에

이해관계자도 많고, 논의도 복잡했어요.

그래서 문서를 정리하고, 일정표를 공유하고, 회의록을 남기는 게 무기가 되었죠.

“1년 차 같지 않다”는 말

그러다 어느 날,

그 용역분께서 이런 말씀을 해주셨어요.

“사실 연지님 1년 차라고 하셔서 놀랐어요. 진짜 그렇게 안 느껴져요.”

그 말을 듣고

살짝 눈물날 뻔했습니다. (진짜로요...)

도태되지 말자, 스스로 다짐하다

하지만 동시에

그분을 보면서 느낀 것도 있어요.

9년 차임에도

최근 트렌드나 기술 스택에 익숙하지 못한 모습에서,

“기술적으로 도태되면 안 된다”는 공포를 느꼈어요.

정말 죄송한 말이지만,

그게 저에겐 강한 자극이 되었습니다.

“착하기만 해선 안 된다. 능력이 있어야 한다.”

이 문장이 마음속에 박혀서

저는 이달부터 더더욱 공부하고 기록하기 시작했어요.

🧪 5월 — 단위 테스트의 철학, 그리고 커리어 코칭

5월은 제 커리어에서 가장 빡세고 가장 큰 교훈을 준 시기였습니다.

요약하자면,

“원래 용역분이 맡았던 프로젝트를, 결국 다시 제가 도맡게 되었습니다.”

정확히 말하면…

원래도 제가 80%는 다 하고 있었어요.

하지만 보안 정책 처리, 문서화, QA 체크 등

“이건 용역분 몫”이었던 부분이 완성되지 못한 채 남게 됐고

결국 마지막까지 책임지고 다 해야 했던 겁니다.

SI 방식의 민낯

이 시점에서 저는 처음으로

SI 개발 방식의 현실적인 문제를 체감했습니다.

• 단위 테스트? 거의 없음.
• 스펙 문서? 중간에 바뀌고 말로 전달됨.
• 기획자 피드백? 말로 말하고 말로 잊혀짐.
• API 연결? 통합 테스트 하나로 퉁치기.

처음엔 “이런 게 원래 그런가 보다” 했지만,

문제가 쌓이고 쌓이니까

점점 시스템이 무너지고, 버그가 뻥뻥 터졌어요.

그걸 다 조용히 뒷정리하고 있는 저 자신을 보면서

진심으로 빡쳤습니다 😇 (진심)

단위 테스트의 철학: mock부터 써라

그때 대표님께서 해주신 말씀이 있어요.

“단위 테스트는 개발자의 철학이다.

mock 없이 API에 의존하는 테스트는, 개발자가 자신도 못 믿는다는 뜻이다.”

이 말을 듣고, 진짜 머리를 한 대 맞은 기분이었어요.

그래서 저는 테스트 철학을 갈아엎었습니다.

✅ 목데이터로 구성해서 유닛 단위로 동작 검증

✅ 통합 테스트는 이후 단계

✅ API 실패/성공/지연 등 상태를 미리 상상하고 대응

✅ 테스트를 코드 설계의 일부로 받아들이기

이후부턴 제 코드에 자부심이 조금씩 생기기 시작했어요.

그리고... 다시 마무리

결국, 그 용역분과의 협업은 종료됐고

모든 QA 대응과 마무리는 제 몫이 되었습니다.

완벽하진 않았지만,

이 경험은 제가 리딩부터 기획, 설계, 테스트, 배포까지

진짜로 ‘혼자서 다 해봤다’는 자신감을 심어줬어요.

그리고 느꼈습니다.

“이제 나는 진짜 개발자다.”

“이젠 누구의 보조가 아닌, 내가 중심인 프로젝트를 만들어가고 있다.”

동시에, 커리어 프로그램도 병행했습니다

이 바쁜 와중에도,

코드잇 커리어 프로그램을 병행하고 있었어요.

이력서 피드백 — 정호영 멘토님의 현실적 조언

저는 이 과정에서

카카오웹툰 프론트엔드 개발자 정호영님께

이력서 피드백을 받았습니다.

정말 꼼꼼하고 직설적인 피드백이 인상 깊었고,

제가 간과했던 부분들 — 예를 들어

“이건 구현은 했지만 결과만 적혀 있고, 과정이 없어요”

“협업 경험이라 쓰셨지만, 구체적인 협업 방식이 빠져 있어요”

같은 부분을 정확히 짚어주셨어요.

덕분에 이력서를 기술 중심 → 문제 해결 중심으로 고쳐 쓰게 되었고,

‘내가 무엇을 했는가’보다 ‘왜, 어떻게 했는가’를 쓰는 게 더 중요하구나를 처음 체감했습니다.

모의 면접 — 다른 멘토님과 진행한 현실 점검의 시간

이후에 진행된 모의 면접은

다른 프론트엔드 멘토님과 진행됐습니다.

그리고 이 시간이 제겐... 꽤 충격이었어요.

질문을 받을 땐 아는 것 같았는데,

막상 말하려니 단어가 안 나오고, 정리가 안 되더라구요.

“나는 기능은 만들 줄 아는데,

원리를 설명할 수는 없구나.”

“기초 개념이 튼튼하지 않으면, 결국 무너질 수밖에 없겠다.”

이걸 뼈저리게 느꼈습니다.

지금도 시간을 쪼개서 하나씩 정리하고 있어요.

그리고... 토스 광탈

그렇게 코칭을 받으면서

“그래도 이참에 도전해보자!” 하고

토스에 이력서를 넣어봤습니다.

결과는요...

광탈이었습니다. 😇

근데 웃긴 건,

이번엔 진짜 괜찮았어요.

왜냐면 그 전까지는

“떨어지면 내 커리어가 끝난 것 같고,

나는 못난 사람인가?” 같은 감정이 컸는데

이번엔 그냥

"내가 아직 준비 안 됐으니까 그렇지. 괜찮아, 다시 채우면 돼.” 이렇게 생각이 들더라고요.

정리하자면…

“5월은 기술적으로도, 정신적으로도

내가 진짜 성장을 시작한 시점이었다.”

• 용역 프로젝트에서 실제 리딩과 마무리를 경험했고
• 커리어 코칭을 통해 나의 얕음, 조급함, 욕심을 정면으로 마주했고
• 테스트와 협업 방식, 개발자 마인드셋이 크게 성장했습니다.

이때 느낀 감정, 배움은

그 어떤 포트폴리오보다 제 성장의 증거가 되었어요.

🌀 6월 — 스카웃, 제안, 유혹… 그리고 “지금 이 자리를 지킨다는 것”

6월은 뭔가 특별하게도,

많은 제안이 한꺼번에 쏟아진 시기였습니다.

먼저,

예전에 함께 일했던 전 직장 상사에게 연락이 왔어요.

“연지씨, 다시 같이 일해볼 생각 없어요?”

갑작스러운 연락에 놀라기도 했지만,

한편으로는 제가 회사에서의 실력과 태도를 좋게 봐주셨다는 뜻 같아서 감사했습니다.

그 뒤로는 진짜 정신없었어요.

서울에서의 헤드헌터 연락,

클래스101에서 강의 제의,

타 회사에서 '연봉 800만 원 더 얹어줄게요'라는 파격 제안까지.

800이라는 숫자,

솔직히 흔들렸어요.

연봉은 곧 제 가치처럼 느껴졌거든요.

“내가 이만큼 받아도 되나?” “받을 자격이 있을까?”

하지만 곰곰이 생각해봤어요.

지금 떠나면, 내가 배울 수 있는 것들을 놓치는 건 아닐까?

지금 회사에선

• Electron이라는 새로운 도전
• 엔진, 파이프, IPC라는 시스템 레벨의 경험
• 보안 도메인의 실무 지식
• 좋은 동료들

이 모든 걸 함께하고 있는데

너무 짧은 시간에 옮겨버리면, 이 소중한 것들을 제대로 흡수하지 못한 채 떠나는 건 아닐까?

그런 마음이 들었어요.

한편으로는 나를 다시 찾아주는 사람도 있고,

기회를 주는 곳도 있다는 것이

“나, 나름 잘해왔구나” 싶은 작은 위로가 되기도 했습니다.

그동안 해왔던 선택이 틀리지 않았다는 걸,

조금은 증명받은 기분이랄까요.

지금 제 일상이 비록 힘들고 녹초가 될 때도 있지만,

저는 여전히 재미있고, 배우고 있다는 걸 부정할 수 없었어요.

그래서 저는

제안들을 전부 정중하게 거절했습니다.

그리고 그 결정이

지금도 마음에 남습니다.

“잘했다”고 말해줄 수 있는 선택이었다고 생각해요.

🧠 총정리 — 나는 부족하고, 욕심 많고, 그래서 성장한다

상반기를 다 돌아보고 나니 머릿속에 제일 많이 남는 감정은 이겁니다.

“나는 부족하고, 욕심이 많고, 그래서 계속 성장하고 싶다.”

저는 여전히

• 서울로 가야 할까 고민하고,
• 좋은 회사에 가고 싶어 하면서도,
• 대전을 떠나기 싫어하고,
• 커리어도, 인간관계도, 사랑도, 다 지키고 싶어하는...

끝도 없이 고민하는 사람입니다.

누구는 “하나만 선택하라”고 하지만

저는 여전히 모든 걸 욕심내는 사람이고

그 욕심 때문에 저는 움직이게 되고, 계속 배우게 되고, 결국에는 성장하게 된다고 믿어요.

그리고 드디어 알게 된 사실 하나.

“선택은 무섭지만, 아무것도 안 하는 건 더 무섭다.”

그래서 이제는

미뤄왔던 개념 공부를 다시 시작하려고 해요.

어설픈 포트폴리오도 정리하고, 사이드 프로젝트도 하나하나 다시 점검하고,

언젠가 꼭 가고 싶었던 회사들을 향해 하나씩 도전하려고 해요.

그리고 한 가지 더.

개발자를 꿈꾼 지 벌써 3년,

개발자로 실제로 일을 한 지는 1년을 조금 넘은 지금,

한 가지 분명하게 말할 수 있는 게 있어요.

요즘 세상은 AI가 개발자를 없앨 거라고 말하곤 합니다.

그리고 저도 그 얘기를 들을 때마다 두려워요. 정말로요.

하지만 그럼에도 불구하고

저는 여전히 ‘개발’이라는 일이 좋습니다.

코드를 짜서 무언가가 제 손으로 완성될 때마다,

머릿속에서 도파민이, 심장에서 옥시토신이 뿜뿜합니다.

그 짜릿한 이쾌감을 저는

앞으로도 내 힘이 닿는 데까지 계속 느끼고 싶어요.

AI가 개발자를 대체한다는 말, 이제는 익숙하죠. 저도 두려워요.

하지만 두려움에 가만히 있을 수는 없잖아요.

그래서 저는 AI를 두려워하기보다, 활용할 줄 아는 개발자가 되고 싶습니다.

주판에서 계산기로, 수기에서 엑셀로 넘어갔듯

AI도 결국엔 “도구”일 뿐이고,

도구는 잘 쓰는 사람이 이깁니다.

처음 주판에서 계산기로, 수기에서 엑셀로 넘어갔듯

AI도 결국엔 “도구”일 뿐이니까요.

잡아먹히지 않기 위해선

계속 배우고, 변화에 반응하고, 스스로를 계속 단련해야 한다는 것도 알게 됐어요.

그래서 저는 지금도 계속 배우고 있어요.

이 직업, 끝없이 공부해야 하는 게 피곤할 때도 있지만

그만큼 계속 새롭고, 계속 재밌습니다.

그래서 저는요, 다 지키는 욕심쟁이가 되고 싶습니다.

개발도 놓치고 싶지 않고,

내 사람들도 놓치고 싶지 않고,

좋은 커리어도 가지고 싶고,

내 삶도 지키고 싶어요.

겁도 나고, 욕심도 많고,

그래도 저는 계속 배우고 걸어가는 사람이고 싶습니다.

잡아먹히지 않기 위해,

계속 배우고, 계속 실험하고, 계속 도전할 거예요. 올 하반기에도 한 발짝씩 묵묵히 걸어가 볼 생각입니다.

🎬 진짜 마무리

2025년 상반기,

저는 무수히 많은 처음을 겪었습니다.

• 처음으로 데스크탑 앱을 만들고
• 처음으로 9년 차 개발자를 리딩하고
• 처음으로 모든 프로젝트를 내 손으로 마무리하고
• 처음으로 나의 부족함을 명확히 인지하고
• 처음으로 커리어 코칭을 받으며 벽을 느끼고
• 그리고 처음으로 정말 많은 제안을 “거절”했습니다.

이 모든 걸 통해

저는 단단해졌고, 더 넓어졌고, 더 겸손해졌습니다.

누군가는 이 글을 보며 이렇게 말할 수도 있어요.

“그렇게 열심히 했는데, 아직도 이직 못했어?”

“대기업 못 갔어?”

그럴 수 있죠. 하지만 저는 말하고 싶어요.

“저는 천천히 그렇지만, 꾸준히 자랄 거에요.”

하반기엔 더더욱 발전해서

언젠가 다음의 회고록은

“내가 꿈꾸던 곳에 도착했다.”

그런 이야기로 마무리할 수 있기를 바랍니다.

읽어주셔서 진심으로 감사합니다.

이 긴 회고록이 누군가에겐 위로이자, 자극이 되었길 바라며

하반기에도 다시 찾아뵐게요 :)

“이 작업, 잘못 붙였다간 블루스크린(BSOD) 뜨는 거 아닌가요?”

실제로 커널 단 작업은 단 하나의 실수만으로도 시스템이 멈추거나 부팅이 불가능해질 수 있습니다. 그렇기 때문에 많은 개발자들이 가상머신(Virtual Machine, VM)을 사용하여 테스트를 진행합니다.

제 메인 PC가 무너지면 저의 하루는 끝이기 때문입니다.

🤔 가상머신을 사용해야 하는 이유

제가 진행하는 작업은 운영체제 깊숙한 곳, 즉 커널 레벨까지 접근하는 작업입니다.

예를 들어 드라이버를 설치하거나, 보안 소프트웨어처럼 시스템 콜을 가로채는 코드들은 예외 처리 한 줄이 누락되면 블루스크린이 발생할 수 있습니다.

• 테스트 서명(bcdedit)을 잘못 켜거나 끄면 부팅 불가
• 드라이버 서명 인증에 실패하면 OS가 실행되지 않음
• 예외 없는 후킹 코드 테스트 시 전체 시스템이 중단

이러한 위험을 안전하게 분리된 공간에서 테스트할 수 있는 유일한 방법이 가상머신을 사용하는 것입니다.

🧾 주요 가상머신 종류 및 장단점 비교

🛠 저는 VMware Workstation을 선택했습니다

제가 VMware를 선택한 이유는 다음과 같습니다.

• Windows 커널 드라이버 테스트를 안전하게 진행할 수 있습니다.
• 스냅샷 기능을 통해 커널 변경 전 상태로 되돌릴 수 있어 실수 복구가 쉽습니다.
• USB 디바이스 테스트가 필요했는데, VMware의 USB passthrough 안정성이 매우 뛰어났습니다.
• 무엇보다 UI가 직관적이어서 복잡한 설정 없이 가상머신을 구성할 수 있었습니다.

💻 VMware Workstation 설치 및 설정 방법

1. VMware 설치 파일 다운로드

• 공식 웹사이트: https://www.vmware.com
• “VMware Workstation Pro” 또는 비상업용 무료인 “Player” 중 선택하였습니다.

2. 설치

• 다운로드한 .exe 파일을 실행하여 기본값으로 설치하였습니다.
• 설치 후에는 시스템 재부팅을 한 번 진행하였습니다.

3. 가상머신 생성

• VMware를 실행한 뒤, “Create New Virtual Machine”을 클릭하였습니다.
• Typical 모드를 선택하였으며, 테스트용으로 Windows 10 ISO 이미지를 지정하였습니다.

4. 가상 디스크 및 저장 위치 설정

• 가상머신 이름은 DriverTest_VM으로 지정하였고, 저장 위치는 SSD 드라이브로 설정하였습니다.
• 디스크 용량은 60GB로 설정하였으며, 성능을 고려하여 “단일 파일로 저장” 옵션을 선택하였습니다.

5. 하드웨어 커스터마이징

• CPU는 2코어 이상, 메모리는 4GB 이상 할당하였습니다.
• USB 장치 연결을 위해 USB 컨트롤러를 활성화하였고, 네트워크는 NAT로 설정하였습니다.
• 디버깅 중 발생할 수 있는 충돌을 방지하기 위해 3D 가속 기능은 비활성화하였습니다.

6. 운영체제 설치

• ISO 이미지를 통해 부팅 후 일반적인 Windows 설치 과정을 진행하였습니다.
• 설치 후 관리자 권한 계정으로 로그인하여 환경을 구성하였습니다.

🔐 커널 테스트를 위한 사전 준비

• bcdedit /set testsigning on 명령어로 테스트 서명 모드를 활성화하였습니다.

  이 명령은 테스트용 드라이버를 설치하거나 커널 레벨 코드를 실행할 수 있게 해줍니다.

  ⚠️ 명령 실행 후에는 가상머신을 재부팅해야 적용됩니다. (실제 PC는 절대 재부팅 금지!)

• Windows Defender와 기타 실시간 보안 프로그램은 임시로 비활성화하였습니다.

  커널 접근 시 과도한 보안 검사로 인한 충돌을 방지하기 위함입니다.

• 시스템 설정 직전에는 반드시 스냅샷을 생성하여 복구 지점을 확보하였습니다.

  문제가 발생할 경우 몇 초 만에 초기 상태로 복구할 수 있도록 준비해두는 것이 중요합니다.

✅ 마무리하며

가상머신은 단순히 보조적인 개발 도구가 아닙니다.

실수해도 안전하게 복구할 수 있는 실험실이자, 시스템 개발의 생명선입니다.

특히 커널 단 드라이버를 테스트하거나, 시스템 레벨에서 작동하는 후킹 또는 보안 코드를 개발하실 때는 반드시 가상머신에서 진행하시는 것을 추천드립니다.

그중에서도 VMware Workstation은 안정성, 편의성, 확장성 면에서 강력한 선택지였습니다.

Electron 앱을 개발하다가 .env 파일로 API 주소 같은 환경변수를 넣고 싶어서 이렇게 작성했어요.

// main.ts
import * as dotenv from 'dotenv';
dotenv.config();

console.log(process.env.VITE_API_BASE_URL1); // ❌ undefined

Node 환경에서 이 방식은 너무 당연하잖아요?

그런데 Electron에서는… 왜 이게 안 될까요?

❓ Electron 메인은 Node 환경 아닌가요?

Electron의 메인 프로세스(Main Process)는 실제로 Node.js 런타임 위에서 실행됩니다.

fs, child_process, path 같은 Node 내장 모듈도 자유롭게 사용할 수 있고,

console.log(process.platform)도 잘 찍혀요.

그래서 대부분의 개발자(저 포함)는 이렇게 생각합니다:

“Node 환경이니까 .env + dotenv + process.env 조합이면 당연히 환경변수 잘 들어오겠지!”

이 생각, 틀린 건 아니에요. Electron은 분명 Node 기반이니까요.

그런데 여기서 하나 간과한 게 있었습니다.

🧩 바로 "Vite를 쓰고 있다는 점"

Electron 프로젝트를 만들 때 Vite를 사용하는 경우가 많습니다.

렌더링 속도 빠르고, 설정 간단하고, React 기반 UI까지 바로 통합되니까요.

그런데…

⚠️ Vite는 단순 실행기가 아니라 정적 빌드 도구입니다.

즉, 우리가 작성한 코드를 실행하는 게 아니라,

미리 빌드해서 정적인 결과물로 만들어주는 도구라는 점입니다.

이건 메인 프로세스(main.ts)도 예외가 아닙니다.

우리가 Vite로 메인도 같이 번들링하면,

그 순간부터는 Node 런타임에 의한 실행이 아니라

Vite가 만들어낸 JS 결과물의 실행이 되는 거예요.

🔍 그럼… 왜 Vite는 process.env를 무시할까?

Vite는 빠른 개발환경과 빌드 성능을 위해 정적 분석(static analysis) 기반으로 작동합니다.

그래서 “코드 안에서 예측 가능한 부분만” 치환해줍니다.

process.env.XXX는 런타임에 정해지는 값이라

Vite 입장에선 “이 값이 뭔지 미리 모른다” → 아예 무시!

반면 import.meta.env.VITE_XXX는

Vite가 .env 파일을 빌드 타임에 읽어서 코드에 직접 박아 넣어줄 수 있는 "정적인 값"입니다.

📦 예시

// 개발자가 작성한 코드
const apiUrl = import.meta.env.VITE_API_BASE_URL1;

⬇ 빌드 후

const apiUrl = "https://api.example.com"; // 정적 치환됨!

반면 이런 건?

console.log(process.env.VITE_API_BASE_URL1);

⬇ 빌드 후에도 여전히

console.log(process.env.VITE_API_BASE_URL1); // undefined

아무 처리도 되지 않은 채 남아 있다가,

실행 시에도 .env를 읽지 않으니 undefined가 되는 거죠.

🧪 그럼 개발 모드에서는 왜 process.env가 작동했던 거예요?

여기서 많은 개발자가 헷갈립니다.

개발 모드에서는 Vite dev server가 Node 기반으로 돌아가고,

일부 경우 process.env 값이 들어가는 것처럼 보일 수 있어요.

이건 사실 Vite가 define 속성이나 dotenv 로딩을 통해 임시로 넣어준 값일 뿐,

"우연히" 동작하는 것일 뿐입니다.

✅ 개발 모드에서는 동작할 수도 있음

❌ 하지만 빌드 모드에서는 100% 무시됩니다

😵 흔히 겪는 착각들

⚙️ Vite vs Node.js – 환경변수 처리 비교

✅ Electron + Vite 환경에서의 결론 정리

그렇다면 .env만 바꾸면 바로 적용되나요? ❌ 아니요!

Vite는 빌드 타임에 .env 파일을 읽어서 코드를 바꾸기 때문에,

.env 변경 후에는 반드시 vite build 같은 빌드 작업을 다시 해야 반영됩니다.

✅ 최종 요약

Electron 메인은 Node 환경이다 → process.env 가능 BUT Vite로 빌드하면 정적 분석 기반 → process.env 무시됨 → import.meta.env.VITE_XXX 만 써야 함!

Vite를 사용하는 순간, "런타임의 유연성"보다

"빌드 시점의 확정성과 정적 최적화"가 더 중요해집니다.

이 차이를 이해하는 것이 Electron + Vite 개발의 핵심이에요.

프론트엔드 개발을 하다 보면 코드 리뷰에서 이런 말을 자주 듣게 됩니다.

“이거 구조분해 안 했어?”

“props에서 구조분해 해주세요”

“store 값 구조분해해서 써주세요”

그렇다면 이 구조분해란 정확히 무엇일까요?

그리고 왜 쓰는 게 좋고, 언제 쓰면 오히려 독이 되는 걸까요?

실전 예시와 함께 정리된 구조분해 가이드를 알려드릴게요.

✅ 구조분해란?

JavaScript(또는 TypeScript)에서 객체나 배열의 값을 개별 변수로 뽑아내는 문법입니다.

const user = { name: '연지', age: 26 };

// 구조분해 없이
const name = user.name;
const age = user.age;

// 구조분해로
const { name, age } = user;

⭐ 구조분해의 장점

예시: props에서 구조분해

// 구조분해 X
function Profile(props: { name: string; age: number }) {
  return <div>{props.name} ({props.age})</div>;
}

// 구조분해 O
function Profile({ name, age }: { name: string; age: number }) {
  return <div>{name} ({age})</div>;
}

🎯 구조분해가 유용한 경우

1. props, context, hook 등에서 여러 값을 가져올 때

const { t } = useTranslation();
const { userProfile } = useUserStore();

2. API 응답, 상태값 등을 가독성 있게 분리할 때

const { data, error } = await fetchData()

3. 컴포넌트 매개변수에서 바로 속성 꺼낼 때

const MyButton = ({ label, onClick }: ButtonProps) => (
  <button onClick={onClick}>{label}</button>
);

⚠️ 구조분해를 피해야 할 경우 (예외 케이스)

1. 중첩된 객체를 깊게 구조분해할 때

// ❌ 너무 깊은 구조분해
const { a: { b: { c, d } } } = obj;

// ✅ Optional chaining으로 접근하는 것이 더 명확
const c = obj?.a?.b?.c;

2. 필드가 너무 많을 때 (ex. props 10개 이상)

// ❌ 너무 많은 변수 풀림
const { a, b, c, d, e, f, g, h, i, j } = props;

→ 이럴 땐 필요한 것만 부분 구조분해하거나, 그냥 props.xxx로 접근

3. 변수명이 충돌할 수 있는 경우

const { name } = user;
const name = '내 이름'; // 💥 충돌

→ 구조분해 시 변수명을 바꿔주는 것이 안전

const { name: userName } = user;

4. 단일 값만 필요할 때

// ❌ 굳이 구조분해할 필요 없음
const { title } = post;
console.log(post.title);

// ✅ 그냥 post.title로 사용하는 게 더 직관적일 수도 있음

5. 로깅이나 디버깅 시

전체 객체를 로그로 보고 싶을 때는 구조분해하지 말고 객체 통째로 넘기는 것이 낫습니다.

console.log(user); // 전체 구조 확인 가능

🧠 구조분해를 쓸지 말지 결정하는 기준

🔚 마무리 정리

✍️ 한 줄 요약

“구조분해는 잘 쓰면 깔끔한 칼, 남용하면 위험한 칼”입니다. 언제 꺼내 쓸지 잘 판단하는 눈이 중요해요 👀”

예를 들면 _getUser, _registerLeader 같은 함수들이죠.

처음엔 단순한 스타일 차이 정도로 생각하기 쉽지만,

실제로는 이 방식이 실무에서 꽤 널리 쓰이는 네이밍 컨벤션이라는 걸 알게 됩니다.

이번 글에서는

• 왜 함수 앞에 _를 붙이는지
• 언제 쓰고 언제 안 쓰는지
• 어떤 상황에서 유용한지
• 실제로 제가 작업한 코드에서 어떻게 적용했는지를 기준으로 정리해 보려고 합니다.

✅ _는 "이건 내부 전용입니다"라는 뜻이에요

TypeScript에서는 클래스 내부가 아니라면 private 접근 제한자를 사용할 수 없습니다.

그래서 함수 이름에 _를 붙여 개발자끼리의 약속처럼 "이건 외부에서 직접 호출하지 마세요"라는 의미를 표현합니다.

이걸 문법적으로 막을 수는 없지만, 의도를 명확히 드러내는 방식이죠.

예를 들어 아래처럼 구조를 나눕니다:

// 내부 전용 - 순수 API 호출
const _getUser = createPostApi('/api/getUser');

// 외부에 노출할 래퍼 함수
export const getUser = (params) => {
  console.log('[API 요청]', params);
  return _getUser(params).then(...).catch(...);
};

이렇게 하면 _getUser()는 실제로는 외부에서 직접 쓰지 않고,

getUser()만 import해서 사용하게 됩니다.

이런 식으로 작성하면 코드를 읽는 사람 입장에서도

“아, 이 함수는 외부에서 직접 쓰는 게 아니라 내부에서만 호출해야겠구나” 하고 자연스럽게 받아들이게 됩니다.

✅ 그럼 모든 함수에 _를 붙여야 할까? 그렇진 않습니다.

실제로 제가 작업했던 프로젝트에서도 모든 API 함수에 _를 붙이지는 않았습니다.

예를 들어 leader.ts 모듈에서는 _registerLeader, _requestManager 등

내부 전용 함수에 _를 붙인 반면,

department.ts 모듈에서는 getDepartments, addDepartment 같은 함수들을 별도 구분 없이 바로 export했습니다.

이 차이는 구조와 의도에 따라 나뉩니다:

✅ 실무에서는 어떤 기준으로 쓰게 될까?

저는 아래 기준 중 하나라도 해당되면 _를 붙여 내부용 함수로 작성하는 편입니다:

• 해당 함수는 axios 같은 순수 API 호출만 처리하고, 사용자 응답 처리나 로깅은 하지 않을 때
• 로깅, 에러 메시지, 토스트 처리 등을 담당하는 래퍼 함수가 따로 있을 때
• 내부적으로만 재사용하고, 외부에는 노출되지 않아야 하는 유틸 로직일 때
• 테스트나 mocking 대상일 뿐, UI 흐름에는 사용되지 않을 때

반대로 아래 상황에서는 _ 없이 함수명을 바로 export합니다:

• 컴포넌트나 다른 모듈에서 직접 호출될 목적으로 만들어진 함수
• 함수 자체가 간단해서 래핑이 필요 없는 경우 (ex. CRUD 단일 처리)
• 별도 래퍼가 존재하지 않고, 그대로 공식 함수 역할을 할 때

팀 컨벤션으로 정리하면 이런 식입니다

API 네이밍 컨벤션

- `_함수명`: 내부 전용 함수. API 요청만 수행. 예외 처리, 사용자 피드백 없음.
- `함수명`: 외부에서 사용하는 공식 함수. 로깅, 에러 핸들링, 응답 가공 포함.
- `use함수명`: React에서 사용하는 커스텀 훅. get 함수 호출을 감싸서 상태 관리.

실제 디렉터리 구조에 적용해보면

/src
  └── api
        └── user.ts           # _getUser, getUser
  └── hooks
        └── useUser.ts        # useUser

• api 폴더에는 _ 접두사가 붙은 내부 API 함수와 래퍼 함수가 함께 정의되고,
• hooks 폴더에는 외부 API를 감싸는 useXXX 형태의 훅이 정의됩니다.

테스트, 유지보수, 협업 모두에 도움이 됩니다

• _함수는 mocking이나 테스트에서 훨씬 다루기 쉬워요.
• export된 래퍼 함수는 외부에서는 항상 일정한 방식으로 응답을 처리하게 만들어 줍니다.
• 또한 역할이 명확하게 나뉘기 때문에, 협업 중에도 함수가 어떤 용도로 쓰이는지 쉽게 파악할 수 있습니다.

//내부 API 함수만 mocking해서 래퍼 함수는 실제 흐름대로 테스트할 수 있습니다.
jest.mock('@/api/user', () => ({
  _getUser: jest.fn().mockResolvedValue(mockData)
}));

📦 래퍼 함수란?

다른 함수(또는 로직)를 감싸서, 추가 동작을 함께 수행하는 함수를 말합니다.

즉, "기존 기능을 그대로 호출하되, 그 앞뒤로 무언가 더 하는 함수"예요.

포장지(wrap)처럼 감싼다고 해서 "래퍼(wrapper)"라는 이름이 붙었어요.

• 래퍼 함수의 역할 요약

> 이렇게 나누면 **책임이 분리되고 코드가 더 읽기 쉬워지고**, 
실수로 순수 함수만 호출해서 문제가 생기는 걸 막을 수 있습니다.
> 

• 간단한 정의로 정리

  래퍼 함수는 어떤 함수나 로직을 감싸서, 부가적인 동작을 함께 수행하는 함수입니다.

  API 요청뿐 아니라, 로깅, 오류 처리, 응답 정리 등을 포함할 때 주로 사용됩니다.

_를 안 쓰면 생기는 문제도 있어요

• 함수의 역할이 모호해져서, 테스트나 구조 분해가 어렵습니다.
• 실수로 내부 함수 (_getUser)를 외부에서 import해서 써버릴 수도 있어요.
• 에러 처리나 로깅 없이 API가 호출되면, 사용자 입장에선 아무 반응이 없어서 불편할 수 있어요.

이런 이유로 대부분의 실무 코드에서는 _를 통해 책임을 분리하고,

함수의 성격에 맞게 구분하는 방식을 선택하고 있습니다.

📌 마무리: 단순한 스타일이 아닌 설계의 결과

함수명 앞에 _를 붙이는 건 단지 네이밍 스타일이 아닙니다.

코드의 책임과 사용 범위를 명확히 하기 위한 실용적인 컨벤션입니다.

• 실수로 잘못된 함수를 import하지 않도록 도와주고
• 테스트와 디버깅을 쉽게 만들어주며
• 코드 구조에 일관성을 부여합니다

특히 복잡한 API 처리, 민감한 보안 기능, 사용자 피드백이 필요한 영역에서는

순수 API 호출과 부가 로직을 분리하는 구조가 큰 도움이 됩니다.

이런 구조는 협업에서도 이해하기 쉽고, 유지보수 시에 의도를 파악하기 쉬워서 장기적으로 효율적인 패턴이 됩니다.

웹소켓 기반 애플리케이션을 운영하다 보면 가장 많이 마주치는 이슈가 바로

👉 "연결이 끊겼는데도 UI는 멀쩡해 보이는 문제"입니다.

특히 절전모드(슬립)나 노트북 덮기, 탭 전환 후 장시간 방치 같은 상황에서는

브라우저가 웹소켓을 끊었음에도 readyState === OPEN 으로 남아있는 경우도 있습니다.

이 글에서는 다음 내용을 다룹니다:

1. ❌ 왜 웹소켓이 끊겼는지 모르고 방치될까?

WebSocket은 브라우저/OS/네트워크 상태에 따라 "조용히 끊길 수 있습니다".

• 절전모드 → 브라우저 프로세스 일시 정지됨
• 네트워크 재연결 → underlying TCP 소켓 끊김
• VPN 변경/라우팅 오류 → 서버 도달 실패
• 방화벽/프록시 → 일정시간 이후 소켓 정리

📌 문제는 webSocket.readyState가 항상 믿을 수 있는 값은 아니라는 것입니다.

2. 🌙 절전모드 감지: 하트비트 방식

가장 많이 쓰는 방식 중 하나는 바로 하트비트(heartbeat).

setInterval(() => {
  const now = Date.now();
  const drift = now - lastTick;
  if (drift > 10000) {
    console.warn('절전모드 감지, 웹소켓 재연결 시도');
    reconnect();
  }
  lastTick = now;
}, 5000);

• performance.timing.navigationStart 또는 Date.now()를 주기적으로 측정
• 예상보다 오래 걸리면 → 절전모드에서 깨어났다고 판단
• → 이 시점에 WebSocket.readyState !== OPEN이거나 이상하면 재연결

✨하트비트(heartbeat)란?

하트비트는 "앱 레벨에서 주기적으로 연결 상태를 감지하는 로직"입니다.

• setInterval로 5초마다 체크
• 연결 상태를 확인하거나, ping 요청을 날려 응답 확인
• 절전모드 감지, 이벤트 루프 delay 감지, 앱의 주기적 상태확인 등에 쓰임

3. 🛰️ WebSocket Ping/Pong 프레임

WebSocket은 RFC 6455 표준에 따라

프로토콜 레벨에서 ping/pong 프레임을 지원합니다.

Ping/Pong 특징

⚠️ 일반 브라우저 JS에서는 ping 프레임을 직접 보낼 수 없습니다.
→ 서버가 ping, 클라이언트가 pong 응답

4. 🏭 실무에서는 어떻게?

- onclose만 쓰면 안 되는 이유

웹소켓을 감시할 때, 많은 분들이 처음엔 이렇게 처리합니다:

const ws = new WebSocket('wss://...');
ws.onclose = () => {
  console.warn('웹소켓 닫힘 → 재연결 시도');
  reconnect();
};

하지만 실무에서는 매우 불안정합니다:

- 문제점들

• 절전모드에서 onclose 발동되지 않음
• 라우팅 장애, VPN 전환 등에서도 readyState는 OPEN 상태 유지
• 서버가 죽어도 클라이언트는 알 수 없음

- 참고: onclose란?

• WebSocket 연결이 정상적으로 종료되었을 때 실행되는 콜백 함수입니다.
• 예를 들어 ws.close()를 호출했을 때나 서버가 명시적으로 연결을 닫을 때 발생합니다.
• 하지만 네트워크 끊김, 절전모드 등은 비정상 종료이기 때문에 onclose가 호출되지 않을 수 있습니다.

✅ 그래서 실무에서는 이렇게 대응합니다

💡 결론: onclose는 일부 상황에서만 유효

• onclose는 정상 종료에만 잘 작동합니다
• 절전모드, 네트워크 오류, VPN, 방화벽 등 실무에서 자주 발생하는 이슈에는 아예 작동 안 하는 경우도 많습니다
• 그래서 반드시 heartbeat 또는 ping/pong을 보완적으로 사용해야 합니다

실무에서는 "둘 다" 병행합니다.

💡 실무에서는 서버가 ping, 클라이언트가 pong 응답하고

프론트는 30초마다 setInterval로 readyState를 감시하는 구조가 일반적입니다.

5. Electron + React + Vite 환경에서의 적용 예시

Electron 앱의 렌더러 프로세스에서는 다음처럼 heartbeat를 구현할 수 있습니다.

// heartbeat.ts
let lastCheck = Date.now();

setInterval(() => {
  const now = Date.now();
  const delay = now - lastCheck;

  if (delay > 10000) {
    console.warn('[하트비트] 절전모드 감지 → 재연결 시도');
    webSocketManager.manualReconnect(); // 커스텀 재연결 로직
  }

  lastCheck = now;
}, 5000);

또는 WebSocket wrapper 클래스 내에서 다음과 같이 상태를 주기적으로 체크할 수 있습니다:

const ws = new WebSocket('wss://...');
setInterval(() => {
  if (ws.readyState !== WebSocket.OPEN) {
    console.warn('연결 끊김 → reconnect');
    reconnect();
  }
}, 10000);

📌 실전 팁 요약

• WebSocket.readyState는 믿되 너무 믿지 말자

  • readyState별 의미 요약 표

    
      | 상태 코드 | 이름        | 의미                       |
      |-----------|-------------|----------------------------|
      | 0         | CONNECTING  | 연결 중                    |
      | 1         | OPEN        | 연결 완료, 송수신 가능     |
      | 2         | CLOSING     | 연결 종료 중               |
      | 3         | CLOSED      | 연결 종료됨                |

• 절전모드, 탭 전환 등은 하트비트로 감지

• 서버는 ping/pong 설정을 적극 활용하자

• Electron 환경에서도 렌더러에 heartbeat는 유용하게 작동

📚 참고자료

• RFC 6455 - The WebSocket Protocol
• MDN - WebSocket
• Socket.IO Heartbeat 참고

보안 기능을 만들면서 실행 파일 감지를 하는데,

생각보다 이런 경로가 많이 튀어나왔다:

C:\ProgramData\Microsoft\Windows\Start Menu\Programs\한셀 2024.lnk

“어? EXE가 아니고 LNK네?”

맞다. 대부분의 사용자는 프로그램을 직접 실행하는 게 아니라 시작메뉴 / 바탕화면 바로가기를 클릭한다.

결국 .lnk 파일을 열어서 실제 실행 대상(EXE 경로)을 뽑아야 한다는 결론에 도달했다.

🔎 LNK 구조 분석 & PowerShell 구현

Windows .lnk 파일은 단순 텍스트가 아니다.

WScript.Shell COM 객체를 통해 접근해야 한다.

PowerShell 스크립트는 간단했다:

powershell
복사편집
$shell = New-Object -ComObject WScript.Shell
$shortcut = $shell.CreateShortcut("C:\경로\한셀 2024.lnk")
$shortcut.TargetPath

이걸 Electron에서 Node.js child_process.spawn()으로 실행하면 끝이다.

그럴 줄 알았다.

💣 문제: “PowerShell에선 되는데 Electron에선 안 된다”

PowerShell 콘솔에선 잘 되는데,

Electron에서 실행하면 결과가 무조건 '' (빈 문자열).

ts
복사편집
// Electron
const result = await execPowerShell('한셀 2024.lnk');
console.log(result); // ''

내가 시도했던 디버깅 1~6단계

🧬 원인 분석

Electron → PowerShell 호출 시, 인자로 전달되는 경로가 한글이면 깨진다.

왜냐면:

• Electron(Node.js)은 기본적으로 UTF-8

• PowerShell은 윈도우 로케일 영향으로 CP949를 쓸 수도 있음

• 그래서 CLI 인자 전달 시 한글이 깨짐

  (CreateShortcut('��� 2024.lnk') ← 이렇게 변형됨)

🤦 “UTF-8로 저장하면 되겠지”는 착각이었다

처음엔 이렇게 생각했다:

“스크립트 파일 자체를 UTF-8 BOM으로 저장하면 되겠지?”

❌ 결과: 안 됨

왜냐하면 깨지는 시점이 스크립트 실행이 아니라, 경로 인자 전달 시점이기 때문이다.

🧠 Base64라는 진짜 해결책

결국 알게 됐다:

Electron → PowerShell 전달 경로를 Base64로 인코딩해서 넘기면 된다.

Base64는 ASCII 문자만으로 구성되어

OS, 로케일, 인코딩 충돌 없이 항상 안전하게 전송된다.

👇 그래서 이렇게 바꿨다:

🔁 Electron:

const encoded = Buffer.from(filePath, 'utf8').toString('base64');
spawn('powershell.exe', ['-File', 'script.ps1', encoded]

🔁 PowerShell:

param($encoded)
$decoded = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($encoded))
$shell = New-Object -ComObject WScript.Shell
$shortcut = $shell.CreateShortcut($decoded)
$shortcut.TargetPath

Boom! 이제 한글 경로도 완벽하게 처리된다.

🧪 왜 Base64만이 해결책인가?

핵심:

UTF-8은 문자열 인코딩이고, Base64는 전송 인코딩이다.

CLI 인자, 파일 경로, JSON 내 인자처럼 전송이 필요한 곳엔 Base64가 정답이다.

✅ 최종 구현 흐름

1. LNK 경로 Base64 인코딩
2. PowerShell에 전달
3. Base64 디코딩 후 CreateShortcut으로 대상 추출
4. 대상 EXE가 존재하면 해당 경로의 파일 메타데이터도 추출

이제 아래처럼 JSON으로 묶어서 반환된다:

{
  "lnk": {
    "filePath": "C:\\...\\한셀 2024.lnk",
    "targetPath": "C:\\Program Files\\HCell.exe",
    "description": "한글 스프레드시트"
  },
  "exe": {
    "progNm": "한셀 2024",
    "prdNm": "HCell",
    "signValid": true}
}

🧠 마무리 회고

처음엔 단순히 “바로가기도 처리해야겠다”는 생각이었는데,

그 끝엔 인코딩 지옥, CLI 디버깅, PowerShell 삽질이 기다리고 있었다.

그나마 다행인 건,

이제는 한글 포함된 모든 바로가기를 완벽하게 처리할 수 있게 됐다는 점이다.

💡 개발자를 위한 TIP: CLI(Command-Line Interface)란?

CLI란?

Command-Line Interface의 줄임말로,

GUI(그래픽 사용자 인터페이스) 없이 명령어를 텍스트로 입력해서 컴퓨터를 조작하는 방식이다.

• 대표 예시:
  • Windows의 cmd.exe, powershell.exe
  • macOS, Linux의 bash, zsh, terminal

# 예시: 파일 경로를 인자로 받아 처리하는 명령
powershell.exe -File myscript.ps1 "C:\Users\연지\문서\바로가기.lnk"

왜 CLI에서 문제가 발생했을까?

• CLI는 텍스트 기반이라 '한글' → byte → 다시 문자열로 변환되는 과정에서 인코딩 오류가 생기기 쉬움
• 특히 PowerShell은 시스템 로케일(예: CP949)을 따라가는 반면, Electron(Node.js)은 UTF-8을 기본으로 사용함
• 이 차이로 인해 CLI 인자로 한글을 넘길 때 깨지는 현상이 발생했다

👉 그래서 해결책은?

Base64 인코딩으로 경로를 감싼 다음 넘기면, CLI 내부에서 무조건 안전하게 처리 가능

CLI에서는 데이터를 다룰 때 문자 그대로 전달되는 게 아니라 바이트 수준의 처리가 되기 때문에,

ASCII만 사용하는 Base64가 매우 안정적인 해결책이 된다.

👇 개발자 여러분, 이건 꼭 기억하세요:

PowerShell에서 잘 된다고 Electron에서도 잘 되리라는 법은 없다.

CLI 인자엔 무조건 Base64를 써라.

아니면 3시간 날릴 수 있다 😇

"개발 모드에선 100% 완벽하게 작동했는데요?"

그 말, 배포 환경 앞에선 무력하다는 걸 여러분도 아시죠?

이번엔 정말 ‘작동’은 했지만 데이터는 안 왔던 미스터리.

그래서 무려 반나절 동안 머리 싸매고 추적한 로그 로그 로그…

결론부터 말하자면?

엔드포인트 오타 + 개발 모드의 과잉 친절 + 배포의 차가움 = 디버깅 지옥

이 긴 여정, 벨로그에 소환합니다.

🛠️ 세팅 요약

🧨 1. 사건 개요

Electron + React + Vite 조합으로 멋지게 GUI 앱을 개발하던 어느 날…

“개발에선 잘 되던 API 호출이 배포 후엔 아무 반응이 없었다.”

기분 좋게 electron-builder로 .exe를 빌드하고 실행했더니,

API는 침묵. 화면은 정지. 내 심장도 멈췄다.

🔍 2. 이상했던 점

• 엔진은 잘 실행됨 ✅
• Pipe 메시지 정상적으로 주고받음 ✅
• 근데 Axios API 요청만 안 감 ❌
• 심지어 콘솔 로그도 안 찍힘 ❌

이쯤 되면 “Electron 배포하면 CORS 문제 생기나?”,

“env 문제인가?”, “build 설정에서 뭘 빼먹었나?” 하는 의심이 차례로 들기 시작했습니다.…

🧪 3. 브레이크 포인트: 오타였다고?

개발 모드에선 잘 되던 이 코드:

axios.post(`${API_BASE}/@@@@@/rest/getAlwCmmnExePrgList.do`)

배포 후에도 잘 될 줄 알았지. 하지만 실제 API는 이거였음:

axios.post(`${API_BASE}/@@@@/rest/getAllowWebList.do`)

즉,

• getAlwCmmnExePrgList.do → ❌ 오타
• getAllowWebList.do → ✅ 올바름

🧙‍♀️ 4. 개발 모드에서는 왜 괜찮았냐면요…

🌈 개발 모드 마법 세트

👉 즉, 오타가 있어도 mock이 받아줌 → 데이터가 응답됨 → 난 문제를 눈치채지 못함...

잠깐! Vite Proxy가 뭐냐면요?

“개발 모드에서는 API 요청을 그냥 localhost로 보내도 잘 되던데요?”

그건 다 Vite의 proxy 기능 덕분입니다.

🎭 프록시란?

프록시는 중간에서 대신 요청을 전달해주는 대리인입니다.

즉, React 앱(렌더러)이 아래처럼 요청하더라도:

axios.post('/@@@@@/rest/getAllowWebList.do', {...})

브라우저는 그걸 http://localhost:3000/@@@@@/rest/getAllowWebList.do로 해석하고,

Vite dev server는 설정에 따라 실제 서버인 https://*******.com:8443로 요청을 자동 전달합니다.

🧪 개발 환경에서 Proxy가 해주는 일

// vite.config.ts
server: {
  proxy: {
    '/@@@@@/rest': {
      target: 'https://*******.com:8443',
      changeOrigin: true,
      secure: false,
    }
  }
}

위 설정이 있다면 /@@@@@@/rest/xxx.do로 오는 요청을

모두 https://*******.com:8443/@@@@@/rest/xxx.do로 프록시해주는 것!

😈 근데 배포(EXE) 모드에서는?

• Vite dev server가 없으니 proxy도 아예 작동 안 함.
• 상대경로(/@@@@@/rest/...)로 호출하면 브라우저는 그냥 file://에서 찾으려 하거나, 아예 URL을 못 찾음.
• 즉, 프록시 없는 배포 환경에서는 절대경로(https://…)를 무조건 써야 함.

💡 그래서 왜 문제가 생긴 걸까?

1. 개발 모드에서는 /####/rest/... → Vite가 프록시로 넘겨줌 → 작동
2. 배포 모드에서는 프록시 없음 → 요청이 날아가지 않거나, 404 에러

💥 5. 배포 후엔 왜 터졌냐면요…

🔥 배포(EXE) 모드의 진실

그러니까...

• 개발 모드에선 오타도 응답이 오지만,
• 배포 모드에선 진짜 서버가 404를 때려버림

🧯 6. 해결한 방법 총정리

🤡 7. 나의 실수 모음 (반성의 표)

✨ 8. 얻은 교훈

“개발 모드는 착한 척할 뿐, 진짜 배포에서 모든 게 드러난다.”

• ✅ 엔드포인트는 반드시 백엔드 문서랑 대조해서 철자까지 정확히
• ✅ 배포 전에 mock 제거하고 실제 서버에 테스트
• ✅ Vite proxy는 개발 전용이라는 걸 잊지 말 것
• ✅ define 치환 방식으로 env 관리하면 실수 줄일 수 있음

🧠 덤: 내 애착 env 설정

# .env.development
VITE_API_BASE=http://localhost:3000

# .env (프로덕션)
VITE_API_BASE=https://********.com:844

vite.config.ts

define: {
  __API_BASE__: JSON.stringify(env.VITE_API_BASE),
}

api.ts

const API_BASE = __API_BASE__;

export function getAllowedWebsites(...) {
  return axios.post(`${API_BASE}/@@@@@@/rest/getAllowWebList.do`, ...);
}

🎉 마무리

이제는 .exe 빌드만 하면 먹통 되는 이유를 안다!

다음에 비슷한 상황이 오면 무조건 3가지를 먼저 확인하자:

1. 엔드포인트 오타나 환경변수 설정 실수는 배포 전 실서버로 반드시 검증하자
2. Vite define 치환은 빌드 시점에 고정되므로, 런타임 수정 불가
3. mock, proxy는 개발을 편하게 해주지만, 배포와는 완전히 다르다

이게 바로 개발 모드의 마법이 배포 모드에서 재앙이 되는 메커니즘 입니다.

이 글이 비슷한 문제로 멘붕하는 분들께 도움이 되었으면 좋겠습니다 🙏

나처럼 안 헤매고 배포까지 쭉쭉 가세요! 🚀

로컬에서는 잘 되던 Engine.exe가

배포만 하면…

🥶 "엔진 파이프에 연결되어 있지 않습니다."

Electron으로 만든 데스크탑 앱을 .exe로 패키징해서 배포했을 때 있었던 실제 사건입니다.

🤔 “로컬에서는 완벽했는데…”

분명 개발 중에는 아무 문제 없었습니다.

• 엔진 잘 뜨고
• Named Pipe도 잘 붙고
• JSON 읽고 쓰고 삭제도 찰떡같이 되더니…

배포하면? 갑자기 연결이 안 됩니다.

🔍 문제 1: asar 안에 들어간 exe는 못 실행합니다

처음엔 이렇게 코드를 짰었죠.

const enginePath = path.join(__dirname, 'public', 'Engine.exe')

로컬에서는 이게 잘 작동합니다.

하지만 Electron Builder가 배포용으로 빌드할 때는…

C:\Users\...\resources\app.asar\public\Engine.ex

app.asar 안에 압축돼버리죠.

문제는 이 상태에서는 .exe 실행이 안 된다는 것!

🛠 해결 1: extraResources + unpack 옵션 추가

그래서 이렇게 electron-builder 설정을 고쳤습니다.

"build": {
  "extraResources": [
    {
      "from": "public",
      "to": "public",
      "filter": ["**/*"],
      "unpack": true}
  ]

그리고 코드에서 경로는 아래처럼 변경했습니다.

const enginePath = path.join(process.resourcesPath, 'app.asar.unpacked', 'public', 'Engine.exe');

이제 드디어 배포 버전에서도 exe가 실행될 줄 알았습니다.

그런데...

😡 문제 2: 언팩도 했는데, 여전히 안 돌아간다고요?

분명히 app.asar.unpacked에 잘 들어가 있는데도 실행이 안 되는 겁니다.

그래서 직접 cmd를 열어서 엔진 경로로 가서 실행해봤습니다.

cd C:\Users\...\resources\app.asar.unpacked\public\
./seph_engine.exe

어랏? 🤯 수동 실행은 되네?

그러니까 문제는 파일이 없어서가 아니라 Electron이 실행을 못 시킨다는 거였던 겁니다.

📦 배포하고 spawn 호출했더니?

아무 일도 일어나지 않았습니다.

아무런 에러도 없이, 아무것도 실행되지 않는 spawn.

Logger.info(`[ENGINE] spawn 성공, PID: ${engineProcess.pid}`);

PID: undefined 👀

아니 뭐…?

😡 “엔진이 죽었습니다”

엔진이 안 돌아가니 Pipe도 연결이 안 됩니다.

[PIPE] reqClient가 null입니다.
[PIPE] reqClient는 writable하지 않습니다.

그리고 사용자에게는 이런 메시지로 가죠.

⚠️ “엔진 파이프에 연결되어 있지 않습니다.”

🔬 디버깅 시작: spawn이 문제였다고?

Electron에서 spawn()은 외부 실행파일을 직접 실행합니다.

하지만 배포 버전에서는 보안 정책 + 경로 문제 + 권한 문제로 인해…

💣 "spawn이 작동 안 합니다"

심지어 경로도 완벽하게 언팩해놨는데요?

C:\Users\me\AppData\Local\Programs\MyApp\resources\app.asar.unpacked\public\seph_engine.exe

이거를 수동으로 cmd에서 실행하면 되는데요?!

Electron만 못합니다 😱

🛠 해결 2: 그래서 결국 exec("start /B")로 해결했습니다

const command = `start /B "" "${enginePath}"`;
exec(command, { cwd: engineDir, windowsHide: true });

start /B는 윈도우 CMD 명령어로 "CMD에서 백그라운드로 실행하라"는 뜻입니다.

Electron이 직접 실행하진 않지만, CMD가 대신 실행해주는 방식입니다.

윈도우에서는 이게 오히려 더 확실하게 실행되더군요.

✔️ 그리고 이 방법으로 드디어 배포에서도 완벽하게 돌아갔습니다!

✨ 최종 요약

😅 마무리하며

개발자 여러분…

“로컬에서는 잘 됐습니다만…”

이 말, 이제 입에 올리지 맙시다…

Electron은 배포가 반입니다. 아니, 배포가 진짜 전쟁입니다. 🪖

혹시 여러분도 배포에서 .exe 실행이 안 돼서 고통받고 계신다면

위 방법 꼭 시도해보세요. 제 반나절을 아낄 수 있습니다 🙏

Electron으로 앱을 개발하고 있었습니다.

기능도 제법 잘 돌아가고, UI도 다듬어지고, "이제 좀 완성 느낌 난다" 싶은 그 타이밍.

그런데요.

누군가 아주 가볍게,

정말 아무렇지도 않게 말하더군요.

"설치파일 주세요~ 😊"

...

머릿속으로 이렇게 외쳤습니다:

“드… 드린다고 했는데… 그걸 내가 만든 적이 있었나…?”

🤯 배포, 그 이름만 들어도

React, Vite, Electron 조합으로 데스크탑 앱을 개발하던 저는

기능 구현, UI 구성, 상태 관리까지 자신 있었지만

"설치 파일 만들기",

그건 뭔가 건들면 안 될 것 같은 금단의 영역처럼 느껴졌습니다.

왠지 진입하면,

• 뭔가 Windows 98 느낌 나는 인스톨 마법사를 만들어야 할 것 같고
• 빌드하려면 인증서부터 발급받아야 할 것 같고
• 깔고 나면 레지스트리 지워야 할 것 같고

...그랬습니다.

그.런.데.

막상 해보니?

세상 간단합니다.

이제 저도 말합니다:

“테스트요? 설치파일 있으니 실행만 해보세요~ 😉”

🎯 목표: 설치부터 업데이트까지

제가 해결한 목표는 아래와 같았습니다:

• Electron 앱을 .exe 설치 파일로 패키징
• 더블클릭으로 설치, 시작메뉴/바탕화면 등록
• 다음 버전 배포 시 별도 안내 없이 자동 업데이트 적용
• 배포 파일을 수동으로 옮기지 않고 자동으로 서버에 올리기
• 내부망에서만 접근 가능한 서버에 안전하게 구성

🛠 기술 스택

🧱 디렉토리 구조 (요약)

project-root/
├── src/                    # React 앱 코드
├── electron/
│   ├── main.ts            # Electron 진입점
│   └── preload.ts         # Preload 스크립트
├── dist/                  # Vite 빌드 결과물
├── dist-electron/         # Electron 빌드 결과물
├── release/               # 설치파일 및 자동업데이트 파일
├── scripts/deploy.js      # 배포 자동화 스크립트
└── vite.config.ts

⚠️ 흰 화면 지옥에서 살아남는 법

Electron에서 자주 겪는 문제 중 하나가 이겁니다:

빌드도 잘 되고 .exe도 잘 실행되는데…

창이 뜨긴 떴는데 아무것도 안 나옴 😱

✅ 원인 99%: 경로 설정 실수

Electron은 브라우저처럼 public 경로가 없습니다.

정확하게 경로를 잡아주지 않으면 로딩 실패 + 흰 화면이 발생합니다.

🧩 해결법

// main.ts
const startUrl = process.env.NODE_ENV === 'development'
  ? 'http://localhost:3000'
  : url.format({
      pathname: path.join(__dirname, '../../dist/index.html'),
      protocol: 'file:',
      slashes: true
    });

✅ 추가: Vite 설정도 꼭

// vite.config.ts
export default defineConfig({
  base: './', // 이거 안 넣으면 JS, CSS 못 불러옴
})

🔄 자동 업데이트 구현: 생각보다 쉽습니다

자동 업데이트를 위해 electron-updater와 electron-log만 설치하면 됩니다:

npm install electron-updater electron-log

핵심 코드 (main.ts)

import { autoUpdater } from 'electron-updater';
import log from 'electron-log';

log.transports.file.level = 'info';
autoUpdater.logger = log;

autoUpdater.checkForUpdatesAndNotify();

autoUpdater.on('update-downloaded', () => {
  autoUpdater.quitAndInstall(); // 앱 꺼지고 재시작됨
});

package.json 설정

"build": {
  "publish": {
    "provider": "generic",
    "url": "http://192.168.0.100:8000/updates/" // 내부 서버 주소
  }
}

자동으로 latest.yml을 기준으로 새 버전이 있으면 다운로드 + 재설치까지 해줍니다.

📦 배포 폴더 구성

빌드 완료 후 release/ 폴더에는 다음 파일이 생깁니다:

release/
├── MyApp Setup 1.0.0.exe     ← 설치용
├── MyApp-1.0.0.exe           ← 자동 업데이트용
├── latest.yml                ← 업데이트 메타 정보

이 세 파일을 서버에 올려두면 자동 업데이트가 됩니다.

🚀 배포 자동화 스크립트

수동으로 서버에 옮기지 않고, 배포를 자동화했습니다.

📁 scripts/deploy.js

const { execSync } = require('child_process');

const files = ['latest.yml', 'MyApp Setup 1.0.0.exe', 'MyApp-1.0.0.exe'];
const server = 'user@192.168.x.x';
const remote = '/var/www/updates/';

files.forEach(file => {
  console.log(`[배포 중] ${file}`);
  execSync(`scp release/"${file}" ${server}:${remote}`);
});

실행 방법

npm run electron:build
node scripts/deploy.js

빌드하고 배포까지 30초 안에 끝납니다.

설치파일 요청 들어오면 이제 “잠깐만요, 바로 올릴게요” 하면 됩니다.

🤖 그런데 자동 업데이트는 도대체 왜 자동으로 되는 걸까요?

Electron 앱이 자동 업데이트를 할 수 있는 건,

electron-updater와 electron-builder가 아주 잘 짜여진 규칙을 공유하고 있기 때문입니다.

이 시스템은 아래처럼 작동합니다:

1. 앱 실행 시, autoUpdater.checkForUpdatesAndNotify()를 호출하면
2. 설정된 서버 주소(publish.url)에 있는 latest.yml 파일을 다운로드합니다.
3. 이 latest.yml에는 현재 배포 중인 최신 버전 정보가 들어 있습니다.

version: 1.0.1
path: MyApp Setup 1.0.1.exe
sha512: <무결성 검사용 해시>

1. 앱의 package.json에 명시된 현재 버전과 비교해서,

2. 최신 버전이 더 높으면 path에 명시된 .exe를 다운로드하고

3. 사용자가 앱을 종료하면 autoUpdater.quitAndInstall()을 통해

   새 설치파일이 자동으로 실행되고 기존 앱은 교체됩니다.

✅ 이게 가능한 이유는?

• electron-builder가 빌드할 때 자동으로 latest.yml과 버전별 .exe를 생성해줍니다.

• electron-updater는 이 latest.yml의 구조를 정확히 이해하고 다운로드 + 설치까지 처리합니다.

• 그리고 우리는 그저… 버전만 올리고, 서버에 올리면 끝.

  즉, 우리가 자동화한 건 배포고, Electron이 자동화해준 건 업데이트 로직입니다.

📦 요약하면 이렇게 됩니다:

👀 실무 팁 모음

• appId는 고정값이어야 자동 업데이트가 정확히 동작합니다.
• version 필드는 반드시 수동으로 올려야 합니다 (자동 업데이트 비교용).
• win.target: 'nsis'는 설치 마법사를 만들어줍니다.
• autoUpdater.checkForUpdatesAndNotify()는 앱 실행할 때마다 업데이트 체크합니다.
• 사용자 로그는 electron-log로 남기면 /AppData/Local/... 에 자동 저장됩니다.

❓ 글을 본 사람들이 추가로 궁금해할 수 있는 질문들

1. “이거 GitHub 같은 공개 저장소 없어도 되나요?”

네, electron-updater는 GitHub를 기본으로 삼지만

provider: "generic"을 쓰면 내부망 서버나 로컬 서버에서도 완벽히 작동합니다.

심지어 사설 IP나 사내 파일서버도 OK입니다.

2. “Setup.exe랑 1.0.0.exe 차이는 뭐예요?”

Setup.exe: 사용자가 처음 설치할 때 쓰는 전체 설치파일MyApp-1.0.0.exe: 자동 업데이트용 패치 파일 (silent install용)

자동 업데이트는 이 작은 -버전.exe만 다운로드해서 설치합니다.

3. “버전은 어떻게 인식해요?”

package.json의 "version": "1.0.1" 값을 사용합니다.

자동 업데이트는 latest.yml의 버전과 비교해서

현재 앱보다 높은 버전이면 실행됩니다.

버전 안 올리고 배포하면 업데이트 안 됩니다.

4. “설치파일 설치하면 어디에 설치돼요?”

기본적으로 Windows의

C:\Users\{username}\AppData\Local\Programs\MyApp\ 경로에 설치됩니다.

electron-builder에서 installDirectory, 아이콘, 실행 권한 등도 설정 가능합니다.

5. “앱 아이콘은 어떻게 바꿔요?”

build 설정에 .ico 파일을 지정하면 됩니다.

"build": {
  "win": {
    "icon": "public/icon.ico"
  }

6. “설치할 때 관리자 권한(UAC) 뜨게 할 수 있나요?”

네! 다음 옵션을 추가하면 됩니다:

"win": {
  "requestedExecutionLevel": "requireAdministrator"
}

그러면 설치할 때 UAC 경고창이 뜨며 관리자 권한으로 실행됩니다.

7. “자동 업데이트 안 되는 경우도 있어요?”

네, 이런 경우에는 동작하지 않습니다:

• latest.yml이 서버에 없거나 URL 설정이 틀림
• version을 이전 버전으로 다시 낮췄을 경우 (다운그레이드 미지원)
• 앱을 UAC 권한 없이 설치했는데, 업데이트 파일이 관리자 권한을 요구함
• 네트워크에서 업데이트 서버 접근이 불가능한 경우

🧘 마무리하며

React + Electron 앱을 설치형으로 배포하려면 뭔가 복잡하고 무서울 것 같았습니다.

하지만 해보니 꽤 재밌고, 은근히 뿌듯하고,

무엇보다 “내가 만든 앱이 진짜로 깔린다”는 경험은 굉장히 짜릿합니다.

웹 개발자도 설치형 앱 만들 수 있습니다.

그리고 그 앱이 알아서 업데이트도 합니다.

그걸 서버에 자동으로 배포하는 스크립트까지 굴러갑니다.

이 글을 여기까지 읽으신 당신도, 지금 바로 npm run electron:build을 해보세요.

❌ Node.js만으로는 사용자의 파일 선택 창을 띄우고 제어할 수 없습니다.

✅ Electron은 Chromium + Node.js 조합이라서 그게 가능한 거예요.

🔍 왜 Node.js는 파일 선택을 못 하는가?

Node.js는 서버 사이드 런타임입니다.

• Node는 백그라운드에서 돌아가는 터미널 기반 애플리케이션을 만들 때 쓰죠.
• 그러니까 사용자에게 UI를 띄운다거나, 마우스로 파일을 고르게 한다거나 하는 건 Node의 역할이 아닙니다.

// Node.js에서는 이런 코드 못 씁니다
dialog.showOpenDialog(...); // UI 없음, 사용자 없음

Node.js에서 파일을 여는 방식은 이런 겁니다:

const fs = require('fs');

fs.readFile('C:/path/to/some/file.exe', (err, data) => {
  // 사용자가 직접 경로를 입력해야 함
});

즉, Node는 파일을 “여는” 건 잘하지만, “고르게 하는” 건 못 합니다.

✅ React + Node.js 조합에서는 어떤 구조?

예시 구조 (웹에서 흔히 쓰는 구조):

[React (프론트엔드)] <--- HTTP 요청 ---> [Node.js (백엔드)]

• React는 <input type="file">로 사용자에게 파일을 선택하게 하고,
• 선택한 파일은 FormData로 Node.js 서버에 업로드합니다.

이 구조에서는 React가 “고르게” 하고, Node가 “받아서 처리”합니다.

❌ 그런데 Node.js만으로 "사용자가 파일을 고르게 하기"는 불가능

Node는 콘솔 기반 런타임이라, 사용자와 시각적인 상호작용을 할 수 없습니다.

파일 선택창 같은 UI는 존재하지 않아요.

// Node.js에서 이런 건 안 됨 ❌
dialog.showOpenDialog(); // Electron에서만 

✅ Electron은 다릅니다

Electron은:

[React (렌더러)] <== IPC 통신 ==> [Node.js (메인 프로세스)]

이 구조라서,

• React가 버튼을 보여주고
• Node가 파일 선택 다이얼로그 띄우고
• 선택한 파일 경로를 다시 React에 전달합니다

이 둘이 서로 IPC로 통신하면서 완전체를 이룹니다. 그래서 가능한 거예요.

✨ 결론

"React는 사용자에게 보여주고 고르게 하는 데 특화돼 있고, Node는 파일을 열고 조작하는 데 특화돼 있어요. 이 둘을 연결하려면 React → 사용자 선택 → Node로 전송 구조가 필요합니다. 하지만 Node만으로는 절대 사용자에게 파일을 '고르게' 할 수는 없습니다."

🧠 쉽게 비유하자면

🎯 진짜 하고 싶은 게 "파일 고르는 시점부터 제어"라면

React + Node.js 구조로는 절대로 불가능합니다.

Electron 또는 WASM + Native bridge 같은 대안을 고려해야 합니다

“사용자한테 .exe만 고르게 하고 싶습니다.

다른 거? .zip? .txt? 고르지도 못하게 해주세요. 클릭도 못 하게요.”

처음엔 정말 그게... 쉬울 줄 알았어요.

🚪 시작은 언제나 <input type="file">

React로 프로젝트를 짜다 보면 파일 선택이 필요하잖아요?

<input type="file" accept=".exe" />

저는 이걸 썼습니다.

그리고 자신만만하게 .exe만 나올 줄 알고 확인 버튼을 눌렀죠.

그런데…

"모든 파일 (.)"

?????? 😨

왜 이게 보여...?

.txt도 선택되고, .pdf도 되고… 온갖 파일이 다 들어오는 겁니다.

“accept는 도대체 왜 준 거야…??” 싶은 순간이었죠.

🔍 React의 accept는 말 그대로 “추천”일 뿐입니다

사실 <input type="file" accept="...">는 "이런 파일이 적절해요~"라는 힌트일 뿐이고,

사용자 선택을 제한할 권한은 없습니다.

브라우저는 보안이 가장 중요하기 때문에,

사용자 파일 시스템을 적극적으로 제한하지 않습니다.

🧨 그래서 결국… 이상한 파일이 들어오고 메타데이터 추출에서 앱이 터지고... 💣

😎 그런데 말입니다. Electron을 쓰면 얘기가 달라집니다

Electron에서는 이렇게 쓸 수 있어요:

const result = await window.electronAPI.openFileDialog({
  title: '실행 파일을 선택하세요',
  filters: [{ name: '실행 파일', extensions: ['exe'] }],
  properties: ['openFile']
});

이 코드 하나면,

✅ .exe 외 확장자? 절대 안 보여요

✅ "모든 파일"? 그런 거 없습니다

✅ .zip? .txt? 선택조차 못 합니다!

Electron은 내부적으로 Node.js를 내장하고 있어서

dialog.showOpenDialog()로 운영체제의 파일 탐색기를 직접 호출합니다.

즉, 이건 힌트가 아니라 진짜 OS에다가 "이거만 보여줘!"라고 말하는 거예요.

🚀 Electron이 가능한 이유: Node.js의 힘

Electron은 내부적으로 Node.js를 내장하고 있고,

파일 시스템, 네이티브 모듈, OS API 등에 자유롭게 접근할 수 있습니다.

그래서 가능해지는 것들:

• fs, path 등을 통한 파일 직접 접근
• child_process로 PowerShell/CLI 호출
• dialog.showOpenDialog()로 확장자 제한 강제
• 심지어 .exe 메타데이터 추출, 서명 확인까지 가능!

웹브라우저는 이걸 못 합니다.

보안이 우선이기 때문에, 사용자 디바이스에 있는 파일을 마음대로 보고, 필터링하고, 실행하고 하는 행위는 제한되죠

⚔️ 이래서 Electron을 씁니다

Electron을 쓰는 이유가 이런 강력한 시스템 제어력 때문 아니겠어요? 😎

파일 선택기 하나도 제대로 다루면 앱이 훨씬 견고해집니다.

❓그럼 Node.js쓰면 파일 선택기를 제한할 수 있나요??

🧁 보너스 🍩: Electron 없이 .exe만 고르게 하려면?

Electron 안 쓰는데 진짜 .exe만 고르게 하고 싶으시다고요?

그럼 이건 크게 두 가지 방법을 고민해보셔야 합니다.

1. 업로드 후 검증

• 사용자가 뭘 업로드하든 서버나 클라이언트에서 검사해서

  .exe 아니면 거절하는 방법입니다.

• 예: MIME 타입 체크, 확장자 검사, 내부 구조 일부 파싱 등

if (!file.name.endsWith('.exe')) {
  alert('이 파일은 .exe가 아닙니다!');
  return;
}

🧨 단점: 사용자 입장에선 이미 파일 고르고도 "안 돼요" 하면 UX가 안 좋아요.

2. 커스텀 파일 업로드 컴포넌트 만들기

• 라이브러리 없이 <input type="file"> 대신

  버튼 + 드래그앤드롭 UI를 만들어서 내부에서 .exe 파일만 거르는 방식입니다

• 브라우저 보안상 "선택 자체를 막는 것"은 불가능하므로,

  선택 후 거르는 UX로 우회해야 합니다

🎬 결론

“accept=".exe" 줬는데도 안 막히네?”

→ 당연한 거였습니다.

브라우저는 권한이 없거든요.

💡 하지만 Electron은 OS에 진짜 말을 걸 수 있는 도구니까요.

dialog.showOpenDialog()를 쓰면

보안성, UX, 실수 방지까지 완벽하게 챙길 수 있습니다.

📌 만약 Electron 없이 이 기능이 꼭 필요하다면?

"제대로 못 막는다는 사실을 알고, 대응 UX를 설계하는 것"이 중요합니다!