개발 환경 구축과 첫 Laravel 프로젝트

개발 환경은 왜 먼저 정리해야 할까

Laravel을 배우는 첫 단계는 문법이 아니라 실행 환경이다. 같은 코드라도 PHP 버전이 맞지 않거나, Composer가 설치되어 있지 않거나, 프론트엔드 빌드 도구가 실행되지 않으면 화면을 볼 수 없다. 초보자에게는 이 지점이 가장 큰 장벽이다.

이번 장의 목표는 단순하다. 내 컴퓨터에서 Laravel 프로젝트를 만들고, 브라우저로 첫 화면을 확인하는 것이다. 이후 라우트, 컨트롤러, Blade, 데이터베이스를 다룰 때도 오늘 만든 프로젝트를 계속 사용한다.

Laravel 개발에 필요한 기본 도구는 다음과 같다.

• PHP: Laravel 애플리케이션을 실행하는 언어

• Composer: Laravel과 PHP 패키지를 설치하는 도구

• Node.js와 npm: CSS, JavaScript 같은 프론트엔드 자산을 빌드하는 도구

• 데이터베이스: 게시글, 사용자, 로그인 정보 등을 저장하는 공간

• 로컬 서버 환경: 내 컴퓨터에서 웹 서버처럼 Laravel을 실행하는 환경

Laravel 공식 설치 문서도 PHP, Composer, Laravel installer, 그리고 프론트엔드 자산 처리를 위한 Node.js와 npm 또는 Bun 설치를 안내한다.¹ 이 책에서는 가장 널리 쓰이는 Node.js와 npm을 기준으로 설명한다.

AI 생성 이미지

Herd를 쓸까, Docker를 쓸까

개발 환경은 크게 두 방향으로 나눌 수 있다.

첫 번째는 내 컴퓨터에 직접 설치하는 방식에 가까운 환경이다. 대표적으로 Laravel Herd가 있다. Herd는 PHP와 웹 서버인 nginx, Composer, Laravel installer 같은 기본 도구를 준비해 Laravel 프로젝트를 빠르게 실행할 수 있게 해 준다. Windows용 Herd 문서는 PHP, nginx, Node.js를 함께 제공한다고 안내하며, *.test 도메인으로 로컬 사이트를 연결할 수 있다.²

두 번째는 Docker 기반 환경이다. Docker는 PHP, 웹 서버, 데이터베이스 등을 컨테이너라는 독립된 실행 공간에 넣어 관리한다. Docker Compose를 사용하면 PHP-FPM, Nginx, PostgreSQL 같은 서비스를 조합해 Laravel 개발 환경을 구성할 수 있다.³

초보자라면 선택 기준을 이렇게 잡으면 된다.

• 빠르게 시작하고 싶다 → Herd 또는 직접 설치 방식

• 팀원과 완전히 같은 환경을 맞추고 싶다 → Docker 기반 환경

• Docker 개념을 아직 모른다 → 처음에는 Herd나 일반 설치로 Laravel 흐름을 먼저 익힌다

• 회사 프로젝트가 Docker를 쓴다 → Docker를 피하지 말고 프로젝트 문서를 따라간다

이 책의 실습은 특정 환경에 강하게 묶지 않는다. 중요한 것은 php, composer, node, npm 명령을 터미널에서 실행할 수 있고, Laravel 프로젝트가 브라우저에서 열리는 상태다.

먼저 터미널에서 다음 명령을 확인해 보자.

php -v
composer -V
node -v
npm -v

각 명령이 버전 정보를 출력하면 기본 준비는 된 것이다. 명령을 찾을 수 없다는 메시지가 나오면 해당 도구가 설치되지 않았거나, 운영체제의 PATH 설정에 연결되지 않은 상태다.

Laravel 프로젝트를 만드는 두 가지 방법

Laravel 프로젝트를 만드는 대표적인 방법은 두 가지다.

laravel new board-app

또는 다음 명령을 사용할 수 있다.

composer create-project laravel/laravel board-app

두 명령 모두 새 Laravel 프로젝트를 만든다. 하지만 성격이 조금 다르다.

laravel new는 Laravel installer를 사용하는 방식이다. 설치 과정에서 테스트 도구, 데이터베이스, 스타터 키트 같은 선택지를 물어볼 수 있다. Laravel을 자주 만들거나, 최신 설치 흐름을 편하게 따라가고 싶다면 이 방식이 좋다.

composer create-project는 Composer가 laravel/laravel 프로젝트 뼈대를 내려받아 새 디렉터리에 설치하는 방식이다. Laravel installer를 따로 설치하지 않아도 되므로 단순하고 범용적이다. 자동 질문이 적고, 명령의 의미가 명확하다.

이 책에서는 프로젝트 이름을 board-app으로 사용한다. 앞으로 게시글 목록을 만들고, 저장하고, 수정하는 작은 게시판 애플리케이션으로 확장할 것이다.

Laravel installer를 사용할 수 있다면 다음처럼 만든다.

laravel new board-app
cd board-app

Laravel installer가 없거나 laravel 명령을 찾을 수 없다면 Composer 방식으로 만든다.

composer create-project laravel/laravel board-app
cd board-app

설치가 끝나면 프로젝트 폴더 안에 app, routes, resources, database, public 같은 디렉터리가 생긴다. 지금은 전부 외우지 않아도 된다. 중요한 것은 Laravel 프로젝트가 여러 역할을 폴더별로 나누어 관리한다는 점이다.

첫 화면 실행하기

Laravel 프로젝트를 실행하는 방법은 개발 방식에 따라 조금 다르다.

가장 기본적인 PHP 서버 실행 명령은 다음과 같다.

php artisan serve

명령이 정상적으로 실행되면 보통 다음 주소에서 애플리케이션을 확인할 수 있다.

http://127.0.0.1:8000

또는 다음 주소로 열릴 수 있다.

http://localhost:8000

여기서 artisan은 Laravel 프로젝트에 포함된 명령 실행 도구다. 앞으로 마이그레이션 실행, 컨트롤러 생성, 테스트 실행 등 많은 작업을 php artisan ... 형태로 처리한다.

다만 최근 Laravel 프로젝트는 PHP 서버만으로 끝나지 않는다. CSS와 JavaScript를 다루기 위해 Vite 개발 서버도 함께 실행하는 경우가 많다. Laravel의 Vite 설정은 기본적으로 resources/css/app.css, resources/js/app.js 같은 파일을 진입점으로 사용하고, npm run dev 명령으로 변경 사항을 감지한다.⁴

처음 프로젝트를 만들었다면 프론트엔드 패키지를 설치한다.

npm install

이 명령은 package.json에 적힌 프론트엔드 패키지들을 node_modules 디렉터리에 내려받는다. 설치가 끝나면 개발 서버를 실행한다.

npm run dev

이제 터미널이 두 개 필요할 수 있다.

첫 번째 터미널:

php artisan serve

두 번째 터미널:

npm run dev

Laravel 버전과 프로젝트 설정에 따라 다음 명령을 사용할 수도 있다.

composer run dev

공식 설치 흐름에서는 이 명령이 Laravel 개발 서버, 큐 워커, Vite 개발 서버 등을 함께 실행하는 편의 명령으로 소개된다.¹ 다만 모든 프로젝트에 항상 같은 스크립트가 있는 것은 아니다. composer.json의 scripts 항목을 확인하면 현재 프로젝트에서 지원하는 명령을 알 수 있다.

.env 파일은 로컬 설정의 중심이다

프로젝트 루트에는 .env 파일이 있다. 이 파일은 현재 컴퓨터에서만 사용할 설정을 담는다.

예를 들면 다음과 같은 값이 들어 있다.

APP_NAME=Laravel
APP_ENV=local
APP_KEY=base64:...
APP_DEBUG=true
APP_URL=http://localhost

DB_CONNECTION=sqlite

.env는 코드와 설정을 분리하기 위해 사용한다. 같은 Laravel 코드라도 내 컴퓨터에서는 SQLite를 쓰고, 운영 서버에서는 MySQL을 쓸 수 있다. 이 차이를 코드에 직접 쓰지 않고 .env에 둔다.

최신 Laravel 설치 흐름에서는 SQLite를 기본 데이터베이스로 사용할 수 있다. SQLite는 별도 데이터베이스 서버를 띄우지 않고 파일 하나로 동작하므로 학습용으로 좋다. Laravel installer로 프로젝트를 만들면 database/database.sqlite 파일이 만들어지고 기본 마이그레이션이 실행되는 경우도 있다. 반대로 Composer 방식이나 선택한 설치 옵션에 따라 상태가 다를 수 있으니, 데이터베이스 오류가 나면 .env와 database 디렉터리를 함께 확인하면 된다.

MySQL이나 PostgreSQL을 사용하려면 .env의 데이터베이스 설정을 바꾸고, 실제 데이터베이스도 먼저 만들어야 한다.

예를 들어 MySQL을 사용한다면 다음처럼 설정할 수 있다.

DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=board_app
DB_USERNAME=root
DB_PASSWORD=

설정을 바꾼 뒤에는 이후에 다룰 마이그레이션을 실행해야 데이터베이스 테이블이 생성된다.

php artisan migrate

지금 당장은 데이터베이스를 깊게 다루지 않는다. 다만 .env는 "내 실행 환경의 설정 파일"이라는 점을 기억하자. 비밀번호, API 키 같은 값도 들어갈 수 있으므로 보통 Git 저장소에 직접 올리지 않는다.

처음 헷갈리는 폴더들

Laravel 프로젝트를 열면 폴더가 많아 보인다. 이번 장에서는 초기에 자주 헷갈리는 폴더만 먼저 정리하자.

public

public은 웹에서 직접 접근 가능한 디렉터리다. Laravel을 배우기 전에 알아야 할 웹과 PHP에서 본 것처럼 Laravel 요청의 진입점은 보통 public/index.php다.

브라우저가 /posts 같은 URL로 요청을 보내면 웹 서버는 프로젝트 전체를 공개하지 않는다. 먼저 public/index.php로 요청을 전달하고, Laravel이 라우터를 통해 적절한 코드를 실행한다.

그래서 이미지, favicon, 빌드된 CSS·JavaScript처럼 공개되어도 되는 파일은 public 아래에 둘 수 있다. 반대로 .env, 컨트롤러, 모델, 설정 파일은 웹에서 직접 열리면 안 된다.

storage

storage는 Laravel이 실행 중에 만들어 내는 파일을 저장하는 공간이다. 로그 파일, 캐시 파일, 업로드 파일, 컴파일된 Blade 파일 등이 이곳과 관련된다.

예를 들어 에러가 발생하면 보통 다음 파일에서 로그를 확인한다.

storage/logs/laravel.log

운영체제나 Docker 환경에 따라 storage에 쓰기 권한이 없으면 Laravel이 로그나 캐시 파일을 만들지 못해 오류가 날 수 있다. "Permission denied"라는 메시지를 만나면 코드보다 먼저 storage 권한을 의심해야 한다.

bootstrap/cache

bootstrap/cache는 Laravel이 빠르게 부팅하기 위해 만든 캐시 파일을 저장하는 곳이다. 설정, 라우트, 서비스 정보 등이 캐시될 수 있다.

개발 중 설정을 바꿨는데 반영되지 않는다면 캐시가 원인일 수 있다. 이때는 다음 명령을 사용한다.

php artisan optimize:clear

이 명령은 설정 캐시, 라우트 캐시, 뷰 캐시 등을 정리할 때 자주 사용한다. 초보 단계에서는 "이상하게 예전 설정이 남아 있다" 싶을 때 기억해 둘 만한 명령이다.

실행 문제를 만났을 때 확인할 순서

처음 프로젝트를 실행하다 보면 오류가 날 수 있다. 그때는 무작정 검색하기보다 아래 순서로 확인하자.

1. 프로젝트 폴더 안에서 명령을 실행했는가?

2. composer install이 필요한 상태는 아닌가?

3. npm install을 실행했는가?

4. .env 파일이 있는가?

5. APP_KEY가 비어 있지는 않은가?

6. 데이터베이스 설정과 실제 데이터베이스가 일치하는가?

7. storage, bootstrap/cache에 쓰기 권한이 있는가?

다른 사람의 프로젝트를 내려받았을 때 .env 파일이 없다면 보통 .env.example을 복사해 만든다.

cp .env.example .env

Windows PowerShell에서는 다음처럼 복사할 수 있다.

Copy-Item .env.example .env

만약 .env는 있는데 APP_KEY가 없다면 다음 명령을 실행한다.

php artisan key:generate

다른 사람의 프로젝트를 내려받았을 때는 보통 vendor 디렉터리가 없다. 이 디렉터리는 Composer가 다시 만들 수 있으므로 저장소에 올리지 않는 경우가 많다. 이때는 다음 명령을 실행한다.

composer install

프론트엔드 파일도 마찬가지다. node_modules는 보통 저장소에 올리지 않으므로 다음 명령으로 다시 설치한다.

npm install

이번 장에서 만든 기준

이제 우리는 Laravel 프로젝트를 만들고 실행할 수 있는 최소 환경을 갖췄다.

정리하면 흐름은 다음과 같다.

laravel new board-app
cd board-app
npm install
php artisan serve
npm run dev

또는 Composer 방식으로 시작할 수 있다.

composer create-project laravel/laravel board-app
cd board-app
npm install
php artisan serve
npm run dev

여기서 핵심은 명령 자체를 외우는 것이 아니다. Laravel 애플리케이션은 PHP 서버가 요청을 받고, Vite가 프론트엔드 자산을 개발 모드로 제공하며, .env가 로컬 설정을 결정한다. public은 웹 진입점이고, storage와 bootstrap/cache는 실행 중 생성되는 파일과 캐시를 다룬다.

Laravel 애플리케이션의 구조와 요청 생명주기에서는 프로젝트 안으로 더 들어간다. 브라우저 요청이 public/index.php를 지나 Laravel 내부에서 어떤 순서로 이동하는지 살펴보고, 폴더 구조가 요청 처리 흐름과 어떻게 연결되는지 확인한다.

참고

¹Laravel Installation 문서

²Laravel Herd Windows Installation 문서

³Docker Laravel Development Setup with Docker Compose

⁴Laravel Vite 문서