0277

FE

[Flutter] 초보자를 위한 Flutter 프로젝트 폴더 구조 완전 정복

오프닝

Flutter 프로젝트를 처음 생성하면 많은 파일과 폴더가 생기고, 각 파일이 어떤 역할을 하는지 헷갈릴 수 있다.

flutter create 명령어로 프로젝트를 만든 뒤, 전체 구조와 각 요소의 용도를 이해하면 개발 속도와 효율이 올라간다.

아래 내용은 공부 목적에 맞춰, 모든 주요 폴더와 파일의 역할을 설명한 것이다.

핵심 작업 영역

수많은 폴더 중, 실제 개발 과정에서 매일 수정하는 영역은 다음 두 곳이다.

  1. lib/ 폴더 — 앱의 대부분의 Dart 코드를 작성하는 폴더이다.

  2. pubspec.yaml 파일 — 앱의 이름, 설명, 버전, 의존성 패키지, 폰트, 이미지 등 리소스를 설정하는 파일이다.

폴더 및 파일 상세 설명

1) lib/

: 앱의 UI, 로직, 상태 관리 등 모든 Dart 코드를 작성하는 메인 작업 공간이다.

  • 기본 파일:

    • main.dart — 앱 실행 시 최초로 호출되는 진입점(Entry Point) 파일이다.main() 함수와 최상위 위젯(MyApp)이 포함되어 있다.

2) pubspec.yaml

: 앱의 메타데이터와 설정을 관리하는 파일이다.

  • 주요 역할:

    • 앱 이름, 설명, 버전

    • dependencies: 사용할 패키지 목록

    • assets, fonts: 이미지, 폰트 등 리소스 등록

3) pubspec.lock

: 설치된 패키지의 정확한 버전을 기록하는 잠금 파일이다.

  • 다른 환경에서 동일한 버전의 의존성을 유지하도록 돕는다.

4) android/

: 안드로이드 네이티브 프로젝트 파일이 들어 있다.

  • 주요 파일:

    • app/build.gradle(.kts): SDK 버전, 의존성 설정

    • AndroidManifest.xml: 권한, 앱 이름·아이콘 등 시스템 정보

5) ios/

iOS 네이티브 프로젝트 파일이 들어 있다.

  • 주요 파일:

    • Runner.xcodeproj: Xcode 프로젝트 파일

    • Info.plist: 앱 메타데이터(이름, 버전, 권한)

    • AppDelegate.swift: 앱 초기화 코드

6) web/

: Flutter 웹 앱 실행을 위한 파일이 들어 있다.

  • 주요 파일:

    • index.html: 웹 앱 기본 HTML

    • manifest.json: PWA 설정

    • icons/: 웹 아이콘 이미지

7) windows/

: Windows 데스크톱 앱 네이티브 코드가 들어 있다.

  • 구성:

    • runner/: C++ 실행 코드(main.cpp 등)

    • resources/: 앱 아이콘

    • CMakeLists.txt: CMake 빌드 설정

8) macos/

: macOS 데스크톱 앱 네이티브 코드가 들어 있다.

  • 구성:

    • Runner/: Swift 기반 앱 엔트리 코드

    • Assets.xcassets: 아이콘, 이미지

    • Configs/: 빌드 설정 파일

    • Runner.xcodeproj, .xcworkspace: Xcode 프로젝트/워크스페이스

9) linux/

: Linux 데스크톱 앱 네이티브 코드가 들어 있다.

  • 구성:

    • runner/: C++ 실행 코드(main.cc, my_application.cc)

    • flutter/: 플러그인 등록 코드

    • CMakeLists.txt: 빌드 설정

10) test/

: 테스트 코드를 작성하는 폴더이다.

  • 기본 파일:

    • widget_test.dart: 샘플 위젯 테스트 코드

11) build/

: 빌드 결과물이 저장되는 폴더이다.

  • Flutter가 자동 생성하며, 수동 수정은 하지 않는다.

12) .dart_tool/

: Flutter와 Dart가 내부적으로 사용하는 데이터가 저장된 폴더이다.

13) .idea/, test_app.iml

: IntelliJ/Android Studio 설정 파일이다.

14) .gitignore

: Git 버전 관리에서 제외할 파일과 폴더를 지정하는 파일이다.

15) analysis_options.yaml

: 코드 스타일 규칙과 정적 분석(Linter) 설정을 정의하는 파일이다.

16) 기타 파일

  • favicon.png, app_icon_XXX.png: 앱 아이콘 파일

  • CMakeLists.txt: 데스크톱 플랫폼 빌드 설정

  • GeneratedPluginRegistrant: 플러그인 자동 등록 코드

수정 빈도 가이드

수정 빈도

폴더/파일

매일 수정

lib/, pubspec.yaml

가끔 수정

test/, android/, ios/, analysis_options.yaml

거의 안 수정

build/, .dart_tool/, .idea/, 데스크톱 CMake 설정

마무리

Flutter 프로젝트 구조를 이해하면 파일과 폴더를 열었을 때 당황하지 않게 된다.

매일 다루는 폴더와 거의 건드리지 않는 폴더를 구분하면 작업 효율이 올라간다.

초보자는 우선 lib/와 pubspec.yaml에 집중하여 코드를 작성하고,
필요할 때만 플랫폼 폴더와 설정 파일을 수정하면 된다.