로컬 개발 환경 구성 및 실행

Laravel 프로젝트를 설치했으니 이제 로컬에서 개발하며 실행하는 방법을 알아보겠습니다. 개발 환경을 제대로 구성하면 효율적으로 Laravel을 개발할 수 있어요!

💡 강의 노트: 로컬 개발 환경은 개발자의 생산성을 좌우하는 중요한 요소입니다. 처음에 잘 설정해두면 나중에 편리해요!

🚀 Laravel 개발 서버 실행하기

기본 개발 서버

Laravel에는 개발용 웹 서버가 내장되어 있어요. 별도의 Apache나 Nginx 설치 없이 바로 시작할 수 있습니다!

# Laravel 개발 서버 실행 (가장 간단한 방법)
php artisan serve

# 실행 결과:
# Starting Laravel development server: http://127.0.0.1:8000
# [Tue Nov 18 15:30:00 2024] PHP 8.4.0 Development Server started

💬 설명:

  • php artisan serve: Laravel 내장 서버 실행
  • 기본 주소: http://127.0.0.1:8000 또는 http://localhost:8000
  • 서버 종료: Ctrl + C

커스텀 호스트 및 포트

다른 주소나 포트를 사용하고 싶다면:

# 다른 포트로 실행
php artisan serve --port=8080

# 다른 호스트로 실행 (네트워크에서 접근 가능)
php artisan serve --host=0.0.0.0 --port=8000

# 커스텀 호스트와 포트
php artisan serve --host=192.168.1.100 --port=3000

🌐 네트워크 접근: --host=0.0.0.0으로 설정하면 같은 네트워크의 다른 기기에서도 접근할 수 있어요 (모바일 테스트 등에 유용!)

🔍 서버 실행 방법 심화 학습

Laravel의 artisan serve 명령은 PHP 언어에서 제공하는 자체 서버 -S 옵션을 쉽게 대체하는 편리한 도구입니다.

📖 상세 가이드

더 자세한 서버 비교와 고급 사용법이 궁금하다면:

📚 Laravel artisan serve vs PHP 내장 서버 완전 비교

이 가이드에서는 다음을 다룹니다:

  • 기본 사용법 3단계 비교
  • 설정 및 옵션 상세 분석
  • 성능 및 메모리 사용량 실제 측정
  • 실무 환경별 권장사항

💡 핵심 요약:

  • Laravel 프로젝트라면 php artisan serve 사용 권장
  • 단순 PHP 테스트라면 php -S 사용 가능
  • 두 명령 모두 개발용이므로 프로덕션에서는 사용 금지

⚙️ 환경 설정 확인

.env 파일 구성

개발 환경에 맞게 .env 파일을 설정해보겠습니다:

# .env 파일 내용 확인
cat .env

개발 환경용 .env 설정:

# 애플리케이션 설정
APP_NAME="JinyPHP Demo"
APP_ENV=local
APP_DEBUG=true
APP_KEY=base64:generated-key-here
APP_TIMEZONE=Asia/Seoul
APP_URL=http://localhost:8000

# 로그 설정 (개발용)
LOG_CHANNEL=stack
LOG_LEVEL=debug

# 데이터베이스 설정 (로컬 PostgreSQL)
DB_CONNECTION=pgsql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_DATABASE=jinyphp_demo_01
DB_USERNAME=jinyphp
DB_PASSWORD=your-password

# 캐시 설정 (개발 시 비활성화)
CACHE_STORE=file
SESSION_DRIVER=file
QUEUE_CONNECTION=sync

# 메일 설정 (개발용)
MAIL_MAILER=log
MAIL_HOST=127.0.0.1
MAIL_PORT=2525
MAIL_USERNAME=null
MAIL_PASSWORD=null

애플리케이션 키 생성

보안을 위해 고유한 애플리케이션 키를 생성하세요:

# 새로운 애플리케이션 키 생성
php artisan key:generate

# 결과 확인
php artisan env:get APP_KEY

🗄️ 데이터베이스 설정

마이그레이션 실행

Laravel의 기본 테이블들을 생성해보겠습니다:

# 마이그레이션 상태 확인
php artisan migrate:status

# 마이그레이션 실행 (테이블 생성)
php artisan migrate

# 샘플 데이터 생성 (선택사항)
php artisan db:seed

💡 마이그레이션이란? 데이터베이스 테이블을 코드로 관리하는 Laravel의 기능이에요. 버전 관리가 가능하고 팀원들과 스키마를 공유할 수 있습니다.

데이터베이스 연결 테스트

# 데이터베이스 연결 확인
php artisan tinker

# Tinker에서 실행:
>>> DB::connection()->getPdo();
>>> User::count();
>>> exit

🎨 프론트엔드 개발 환경

Node.js 의존성 설치

CSS와 JavaScript 개발을 위해 Node.js 패키지를 설치하세요:

# package.json 확인
cat package.json

# 의존성 설치
npm install

# 개발 의존성까지 모두 설치
npm ci

에셋 빌드 및 감시

CSS, JavaScript 파일 개발:

# 개발용 빌드 (한 번만)
npm run dev

# 파일 변경 감시 (자동 빌드)
npm run watch

# 프로덕션 빌드 (최적화된 파일)
npm run build

✨ Hot Module Replacement (HMR):

# 실시간 새로고침과 HMR
npm run hot

# Vite 개발 서버 실행
npm run dev

🔧 개발 도구 설정

Laravel Debugbar

디버깅을 위한 유용한 도구:

# Laravel Debugbar 설치 (개발용)
composer require barryvdh/laravel-debugbar --dev

# 설정 파일 발행
php artisan vendor:publish --provider="Barryvdh\Debugbar\ServiceProvider"

Debugbar 활성화 (.env):

APP_DEBUG=true
DEBUGBAR_ENABLED=true

Laravel Telescope (모니터링)

애플리케이션 모니터링 도구:

# Telescope 설치
composer require laravel/telescope --dev

# Telescope 설치
php artisan telescope:install

# 마이그레이션 실행
php artisan migrate

Telescope 접속: http://localhost:8000/telescope

💻 IDE 및 에디터 설정

VS Code 확장 프로그램

Laravel 개발에 유용한 VS Code 확장:

// 추천 확장 프로그램
{
  "recommendations": [
    "bmewburn.vscode-intelephense-client",
    "onecentlin.laravel-extension-pack",
    "ryannaddy.laravel-artisan",
    "codingyu.laravel-goto-view",
    "amiralizadeh9480.laravel-extra-intellisense",
    "bradlc.vscode-tailwindcss"
  ]
}

Workspace 설정

.vscode/settings.json 파일 생성:

{
  "php.suggest.basic": false,
  "php.validate.executablePath": "/usr/bin/php",
  "intelephense.files.exclude": [
    "**/node_modules/**",
    "**/vendor/**/*.js"
  ],
  "files.associations": {
    "*.blade.php": "blade"
  },
  "emmet.includeLanguages": {
    "blade": "html"
  },
  "blade.format.enable": true
}

🧪 테스팅 환경

PHPUnit 설정

Laravel의 기본 테스팅 프레임워크:

# 테스트 실행
php artisan test

# 특정 테스트 실행
php artisan test --filter=UserTest

# 커버리지 확인 (xdebug 필요)
php artisan test --coverage

테스트 데이터베이스

테스트용 별도 데이터베이스 설정 (.env.testing):

# .env.testing 파일 생성
APP_ENV=testing
DB_CONNECTION=pgsql
DB_DATABASE=jinyphp_demo_01_test

# 테스트 시 메모리 DB 사용
DB_CONNECTION=sqlite
DB_DATABASE=:memory:

🚀 개발 워크플로우

일반적인 개발 순서

효율적인 Laravel 개발 흐름:

# 1. 서버 시작
php artisan serve

# 새 터미널에서
# 2. 프론트엔드 감시
npm run watch

# 새 터미널에서
# 3. 큐 워커 실행 (백그라운드 작업용)
php artisan queue:work

# 새 터미널에서
# 4. 테스트 감시
php artisan test --watch

Git 워크플로우

코드 변경 관리:

# 변경사항 확인
git status

# 스테이징
git add .

# 커밋
git commit -m "Add user authentication feature"

# 원격 저장소 푸시 (배포는 별도 섹션에서)
git push origin develop

🔨 유용한 Artisan 명령어

개발 중 자주 사용하는 명령어

# 캐시 클리어
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

# 모든 캐시 클리어
php artisan optimize:clear

# 라우트 목록 확인
php artisan route:list

# 설정 확인
php artisan config:show

# 큐 작업 확인
php artisan queue:work
php artisan queue:status

코드 생성 명령어

# 컨트롤러 생성
php artisan make:controller UserController

# 모델 생성 (마이그레이션과 함께)
php artisan make:model Post -m

# 미들웨어 생성
php artisan make:middleware CheckAge

# 폼 리퀘스트 생성
php artisan make:request StoreUserRequest

# 시더 생성
php artisan make:seeder UserSeeder

📊 성능 모니터링

쿼리 로그 활성화

데이터베이스 쿼리 모니터링:

// AppServiceProvider.php에 추가
use Illuminate\Support\Facades\DB;

public function boot()
{
    if (app()->environment('local')) {
        DB::listen(function ($query) {
            logger()->info('Query executed', [
                'sql' => $query->sql,
                'bindings' => $query->bindings,
                'time' => $query->time
            ]);
        });
    }
}

메모리 사용량 확인

# 현재 메모리 사용량
php -d memory_limit=512M artisan inspire

# 자세한 성능 정보
php artisan about

📂 프로젝트 구조 이해

Laravel 주요 디렉터리

jinyphp_demo_01/
├── app/                    # 애플리케이션 코드
│   ├── Http/Controllers/   # 컨트롤러
│   ├── Models/            # Eloquent 모델
│   ├── Providers/         # 서비스 프로바이더
│   └── ...
├── config/                # 설정 파일
├── database/              # 마이그레이션, 시더
├── resources/             # 뷰, 에셋, 언어파일
│   ├── views/            # Blade 템플릿
│   ├── css/              # CSS 파일
│   └── js/               # JavaScript 파일
├── routes/                # 라우트 정의
│   ├── web.php           # 웹 라우트
│   └── api.php           # API 라우트
├── storage/               # 로그, 세션, 캐시
├── tests/                 # 테스트 파일
└── vendor/                # Composer 의존성

🌍 다중 환경 관리

환경별 설정

.env 파일 종류:

.env                # 메인 환경 설정
.env.local         # 로컬 개발용
.env.testing       # 테스트용
.env.staging       # 스테이징용
.env.production    # 프로덕션용

환경 전환

# 현재 환경 확인
php artisan env:get APP_ENV

# 특정 환경으로 설정
export APP_ENV=testing
php artisan config:cache

❓ 자주 발생하는 문제 해결

Q1: “php artisan serve” 실행 안 됨

A: PHP 경로 확인:

which php
php --version
export PATH="/usr/local/bin:$PATH"

Q2: 데이터베이스 연결 에러

A: 데이터베이스 서비스 상태 확인:

# PostgreSQL 확인
brew services list | grep postgresql
sudo systemctl status postgresql

# MySQL 확인
brew services list | grep mysql
sudo systemctl status mysql

Q3: npm 명령어 실행 안 됨

A: Node.js 버전 확인:

node --version
npm --version
# 필요시 Node.js 재설치

Q4: 권한 에러 (storage/logs)

A: 폴더 권한 설정:

chmod -R 755 storage
chmod -R 755 bootstrap/cache

Q5: Composer 메모리 부족

A: 메모리 제한 늘리기:

php -d memory_limit=2G /usr/local/bin/composer update

🎯 다음 단계

로컬 개발 환경 구성이 완료되었습니다! 이제:

  1. JinyPHP 패키지 설치 → JinyPHP 설치 가이드
    • Laravel 기능 확장하기
  2. 실제 개발 시작
    • 라우팅 학습
    • 컨트롤러와 뷰 만들기
    • 데이터베이스 모델 작성
  3. 실서버 배포 준비 → 서버 배포 가이드
    • 프로덕션 환경 설정

📚 개발 환경 체크리스트

기본 환경

  • Laravel 개발 서버 정상 실행 (http://localhost:8000)
  • .env 파일 구성 및 APP_KEY 생성
  • 데이터베이스 연결 테스트 완료

프론트엔드

  • Node.js 의존성 설치 완료 (npm install)
  • 에셋 빌드 테스트 (npm run dev)
  • 파일 감시 설정 (npm run watch)

개발 도구

  • VS Code 확장 프로그램 설치
  • Laravel Debugbar 설치 및 활성화
  • Git 저장소 초기화

테스팅

  • PHPUnit 테스트 실행 확인
  • 테스트 데이터베이스 구성

네비게이션

핵심 요약

로컬 개발 환경 구성으로 효율적인 Laravel 개발이 가능합니다.

  • php artisan serve: 개발 서버 실행
  • .env 파일: 환경별 설정 관리
  • npm run watch: 프론트엔드 파일 감시
  • Laravel Debugbar: 디버깅 도구

다음 장에서는 JinyPHP 패키지를 설치하여 Laravel을 더욱 강력하게 확장해봅시다!

마지막 업데이트: 2025-11-18 Laravel 12 & PHP 8.4 기준