Windows 도커 환경에서 Laravel Breeze CSS 깨짐 해결법 (WSL2에서 Vite 개발 서버를 실행할 때)

이전 포스트에서는 라라벨 13에 Laravel Breeze를 설치했다.

오늘의 포스트에서는 Windows docker 개발 환경에서 Laravel Breeze 설치 시에 화면의 CSS가 깨진 채로 표시되는 문제를 해결하는 방법을 정리해 보겠다.

이전 포스트

라라벨 13에 Laravel Breeze 설치하기 (Could not resolve './bootstrap' in resources/js/app.js 에러 해결 방법)

라라벨 13에서 Breeze를 설치할 때 발생하는 Could not resolve './bootstrap' in resources/js/app.js 에러 해결 방법을 공유하고, 각 스택(Blade, Livewire, React/Vue)별 차이점도 정리했습니다.

이전 포스트의 마지막에 말했던 것처럼 Windows 운영체제에서 docker로 개발 환경을 구축하면, Laravel Breeze 설치 후 http://localhost에 접속할 때 이렇게 화면의 스타일이 깨져서 이상하게 표시된다.

이 문제를 해결하기 위해서는 총 4개의 파일을 수정해야 한다.

docker-compose.yml

ports:
  - ${VITE_PORT}:${VITE_PORT}

위의 캡처 이미지처럼 docker-compose.yml 파일에서 app:에 해당하는 부분이 이 코드를 추가한다.

.env

VITE_PORT= #넣고 싶은 포트 번호를 넣는다. 보통은 5173

docker-compose.yml 파일에 환경 변수가 추가되었으니 최상위에 있는 .env 파일에도 이렇게 포트 설정값을 추가하자.

도커 컨테이너는 독립된 방과 같다.

이렇게 ${VITE_PORT} 포트를 열어줌으로써, Windows 브라우저가 컨테이너 안에 갇혀 있는 Vite 서버로 접근할 수 있도록 대문을 만든 것이다.

src/package.json

"dev": "vite --host",

위의 캡처 이미지처럼 package.json 파일에는 "dev": "vite",였던 코드를 이렇게 수정한다.

(참고로 VSCode에서 [ctrl + P] 키를 누르고 파일명으로 검색하면 파일의 위치를 빨리 찾을 수 있다.)

기본적으로 Vite는 보안을 위해 '나 자신(컨테이너 내부)'의 요청만 받는다.

그런데 이렇게 --host 옵션을 붙이면 외부(Windows 호스트)에서 오는 요청도 받도록 허락하게 된다.

마지막으로 vite.config.js 파일에는 이 코드를 추가한다.

Asset Bundling (Vite) | Laravel 13.x - The clean stack for Artisans and agents

Laravel is a PHP web application framework with expressive, elegant syntax. We've already laid the foundation — freeing you to create without sweating the small things.

laravel.com

캡처한 이미지의 코드는 Laravel 공식 웹사이트에서도 "WSL2에서 Vite 개발 서버를 실행할 때, 브라우저가 개발 서버와 통신할 수 있도록 vite.config.js 파일에 다음 구성을 추가해야 한다"라고 안내되어 있는 코드다.

src/vite.config.js

server: {
    host: true,
    port: process.env.VITE_PORT ? parseInt(process.env.VITE_PORT) : 5173,
    hmr: {
        host: 'localhost',
    },
},

캡처한 이미지보다 코드가 조금 더 추가됐다.

추가된 코드는 처음에는 필요 없지만, 언젠가 갑자기 포트 번호가 충돌해서 바꿔야 할 경우에는 필요해질 수 있는 코드들이다.

HMR(Hot Module Replacement)은 코드 수정 시 실시간으로 반영해 주는 기능이다.

브라우저에게 "실시간 업데이트 신호를 보낼 주소는 localhost야"라고 명확히 가리켜준 것이다.

docker-compose up -d --build

그리고 마지막으로, 우분투 터미널로 docker-compose.yml 파일이 있는 디렉토리에서 이 명령어를 실행한다.

make app #컨테이너 안으로 들어간다.
npm run dev

그러고 나서 VSCode의 터미널에서 이 명령어들을 다시 입력하고 http://localhost에 접속하면 Laravel Breeze가 설치된 첫 페이지가 드디어 정상적으로 표시될 것이다.

첫 화면의 상단에 Laravel Breeze를 설치하기 전에는 없었던 Log in과 Register 버튼이 보인다.

결과적으로, 이전에는 브라우저가 CSS 파일을 찾으러 컨테이너로 가려다 길을 잃어 CSS가 깨졌던 것이다.

그런데 지금의 설정으로 이정표와 대문을 다 만들어서 정상적으로 파일을 가져오게 된 것이다.

다음 포스트

VSCode를 DB 툴처럼! SQLTools 익스텐션 설치 및 도커 연결 가이드

VSCode에서 직접 데이터베이스(DB)를 조회할 수 있는 'SQLTools' 익스텐션 사용법을 정리했습니다. 별도의 DB 툴 설치 없이 도커 환경의 MariaDB와 연동하는 방법부터 상세한 설정 항목 설명, 그리고 .vscode 디렉터리 관리 팁까지 확인해 보세요.