Flutter 웹앱 배포 시 라우팅 404 문제 해결

문제 상황

사내 어드민 도구를 Flutter Web 베타로 만들어 Firebase Hosting에 배포했다. 처음 접속은 정상이지만 /users 같은 서브 페이지에서 새로고침하면 404 에러가 발생했다.

Flutter 웹은 SPA(Single Page Application)인데, 서버는 실제 /users 경로를 찾으려고 하기 때문이다.

해결 방법

Firebase Hosting 설정에서 모든 요청을 index.html로 리다이렉트하도록 수정했다.

// firebase.json
{
  "hosting": {
    "public": "build/web",
    "ignore": [
      "firebase.json",
      "**/.*",
      "**/node_modules/**"
    ],
    "rewrites": [
      {
        "source": "**",
        "destination": "/index.html"
      }
    ]
  }
}

이렇게 하면 모든 경로 요청이 index.html을 반환하고, Flutter의 클라이언트 라우터가 실제 페이지를 처리한다.

추가 고려사항

Nginx를 사용한다면 try_files 지시문으로 동일하게 처리할 수 있다.

location / {
  try_files $uri $uri/ /index.html;
}

Flutter 웹은 아직 베타라 프로덕션 용도로는 조심스럽지만, 사내 도구 정도는 충분히 활용 가능했다. 빌드 시간이 다소 길고 번들 사이즈가 큰 점은 개선이 필요해 보인다.