Twitter Follow

GitHub stars

Discord

<img width="350px" src="https://cdn.lightpanda.io/assets/images/github/execution-time-v2.svg">

 
<img width="350px" src="https://cdn.lightpanda.io/assets/images/github/memory-frame-v2.svg">

벤치마크 (Benchmarks)

AWS EC2 m5.large 인스턴스에서 네트워크를 통해 933개의 실제 웹 페이지를 요청함.
벤치마크 상세 내용을 참조하세요.

빠른 시작 (Quick start)

설치 (Install)

패키지 관리자 (Package Managers)

Homebrew의 최신 나이틀리 (nightly) 버전:

brew install lightpanda-io/browser/lightpanda

Arch Linux 사용자 저장소 (AUR)의 최신 나이틀리 (nightly) 버전:

yay -S lightpanda-nightly-bi

나이틀리 빌드 (nightly builds)에서 다운로드

나이틀리 빌드에서 x86_64 및 aarch64를 모두 지원하는 Linux 및 MacOS용 최신 바이너리를 다운로드할 수 있습니다.

Linux용

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-x86_64-linux && \
chmod a+x ./lightpanda

무엇인가를 실행하기 전에 바이너리를 확인하세요:

./lightpanda version

Linux aarch64 버전도 사용 가능합니다

참고: Linux 릴리스 바이너리는 glibc에 링크되어 있습니다. musl 기반 배포판(Alpine 등)에서는 glibc 동적 링커 (dynamic linker)가 없기 때문에 cannot execute: required file not found 오류와 함께 바이너리 실행에 실패합니다. glibc 기반 베이스 이미지(예: FROM debian:bookworm-slim 또는 FROM ubuntu:24.04)를 사용하거나 소스에서 빌드하세요.

MacOS용

curl -L -o lightpanda https://github.com/lightpanda-io/browser/releases/download/nightly/lightpanda-aarch64-macos && \
chmod a+x ./lightpanda

MacOS x86_64 버전도 사용 가능합니다

Windows + WSL2용

Lightpanda는 네이티브 Windows 바이너리를 제공하지 않습니다. 위의 Linux 단계를 따라 WSL 내부에서 설치하세요.

WSL이 설치되어 있지 않습니까? 관리자 셸에서 wsl --install을 실행하고, 재부팅한 다음 wsl을 여세요. 자세한 내용은 Microsoft의 WSL 설치 가이드를 참조하세요.

사용자의 자동화 클라이언트 (Puppeteer, Playwright 등)는 WSL 내부 또는 Windows 호스트에서 실행할 수 있습니다. WSL은 localhost:9222를 자동으로 포워딩합니다.

Docker로 설치하기

Lightpanda는 Linux amd64 및 arm64 아키텍처 모두를 위한 공식 Docker 이미지를 제공합니다.
다음 명령은 Docker 이미지를 가져와서 9222 포트로 Lightpanda의 CDP 서버를 노출하는 새 컨테이너를 시작합니다.

docker run -d --name lightpanda -p 127.0.0.1:9222:9222 lightpanda/browser:nightly

URL 덤프하기

./lightpanda fetch --obey-robots --dump html --log-format pretty  --log-level info https://demo-browser.lightpanda.io/campfire-commerce/

--dump markdown을 사용하여 직접 마크다운 (markdown)으로 변환할 수 있습니다.
덤프 전 대기 시간을 조정하려면 --wait-until, --wait-ms, --wait-selector 및 --wait-script를 사용할 수 있습니다.

CDP 서버 시작하기

./lightpanda serve --obey-robots --log-format pretty  --log-level info --host 127.0.0.1 --port 9222

CDP 서버가 시작되면, browserWSEndpoint를 설정하여 Puppeteer 스크립트를 실행할 수 있습니다.

import puppeteer from 'puppeteer-core';

// browserWSEndpoint를 사용하여 Lightpanda의 CDP 서버 주소를 전달합니다.
...

네이티브 MCP 및 스킬 (skill)

MCP 서버는 stdio를 통해 MCP JSON-RPC 2.0 방식으로 통신합니다.

MCP 설정에 다음을 추가하세요:

{
  "mcpServers": {
    "lightpanda": {
...

전체 문서 읽기

스킬 (skill)은 lightpanda-io/agent-skill에서 사용할 수 있습니다.

텔레메트리 (Telemetry)

기본적으로 Lightpanda는 사용 텔레메트리 (usage telemetry)를 수집하고 전송합니다. 이는 환경 변수 LIGHTPANDA_DISABLE_TELEMETRY=true를 설정하여 비활성화할 수 있습니다. Lightpanda의 개인정보 처리방침은 다음에서 확인할 수 있습니다: https://lightpanda.io/privacy-policy.

상태

Lightpanda는 베타 (Beta) 단계이며 현재 개발 진행 중입니다. 안정성과 커버리지는 개선되고 있으며 현재 많은 웹사이트가 정상적으로 작동합니다. 여전히 오류나 충돌이 발생할 수 있습니다. 만약 발생한다면 구체적인 내용을 포함하여 이슈 (issue)를 생성해 주세요.

현재 구현된 주요 기능은 다음과 같습니다:

• CORS #2015
• HTTP 로더 (Libcurl)
• HTML 파서 (html5ever)
• DOM 트리
• 자바스크립트 (Javascript) 지원 (v8)
• DOM API
• Ajax
  • XHR API
  • Fetch API
• DOM 덤프 (dump)
• CDP/웹소켓 (websockets) 서버
• 클릭 (Click)
• 입력 폼 (Input form)
• 쿠키 (Cookies)
• 사용자 정의 HTTP 헤더 (Custom HTTP headers)
• 프록시 (Proxy) 지원
• 네트워크 인터셉션 (Network interception)
• --obey-robots 옵션을 통한 robots.txt 준수

참고: 수백 개의 Web API (Web APIs)가 존재합니다. 브라우저를 개발하는 것(심지어 헤드리스 모드(headless mode)만을 위한 것이라도)은 거대한 작업입니다. 지원 범위는 시간이 지남에 따라 늘어날 것입니다.

소스 코드로 빌드하기 (Build from sources)

사전 요구 사항 (Prerequisites)

Lightpanda는 Zig 0.15.2로 작성되었습니다. 프로젝트를 빌드하려면 반드시 올바른 버전을 설치해야 합니다.

Lightpanda는 또한 v8, Libcurl, html5ever에 의존합니다.

v8 엔진을 빌드하려면 몇 가지 라이브러리를 설치해야 합니다:

Debian/Ubuntu 기반 Linux의 경우:

sudo apt install xz-utils ca-certificates \
    pkg-config libglib2.0-dev \
    clang make curl git

또한 Rust를 설치해야 합니다.

Nix를 사용하는 시스템의 경우, devShell을 사용할 수 있습니다:

nix develop

MacOS의 경우, cmake와 Rust가 필요합니다.

brew install cmake

빌드 및 실행 (Build and run)

make build를 사용하여 전체 브라우저를 빌드하거나, 디버그 환경(debug env)을 위해 make build-dev를 사용할 수 있습니다.

또는 zig 명령어를 직접 사용할 수도 있습니다: zig build run.

v8 스냅샷 임베딩 (Embed v8 snapshot)

Lightpanda는 v8 스냅샷(v8 snapshot)을 사용합니다. 기본적으로 시작 시 생성되지만, 다음 명령어를 사용하여 임베딩할 수 있습니다:

스냅샷 생성:

zig build snapshot_creator -- src/snapshot.bin

스냅샷 바이너리를 사용하여 빌드:

zig build -Dsnapshot_path=../../snapshot.bin

자세한 내용은 #1279를 참조하세요.

테스트 (Test)

단위 테스트 (Unit Tests)

make test를 실행하여 Lightpanda를 테스트할 수 있습니다.

make test                                       # 모든 테스트 실행
make test F="server"                            # 부분 문자열로 필터링
TEST_FILTER="WebApi: #selector_all" make test   # 메인 + 서브 테스트 필터링 (구분자: #)
...

엔드 투 엔드 테스트 (End to end tests)

엔드 투 엔드 테스트 (End to end tests)를 실행하려면, demo repository를 ../demo 디렉토리로 클론(clone)해야 합니다.

demo의 node 요구사항을 설치해야 합니다.

또한 Go v1.24 이상의 버전을 설치해야 합니다.

make end2end

Web Platform Tests

Lightpanda는 표준화된 Web Platform Tests (WPT)를 통해 테스트됩니다.

우리는 커스텀 testharnessreport.js가 포함된 포크(fork) 버전을 사용합니다.

참고로, wpt.live를 통해 브라우저에서 WPT 테스트 케이스를 쉽게 실행해 볼 수 있습니다.

WPT HTTP 서버 설정

테스트를 실행하려면 저장소를 클론하고, 커스텀 호스트(hosts)를 설정하며, MANIFEST.json 파일을 생성해야 합니다.

fork 브랜치로 저장소를 클론합니다.

git clone -b fork --depth=1 git@github.com:lightpanda-io/wpt.git

wpt/ 디렉토리로 이동합니다.

/etc/hosts 파일에 커스텀 도메인을 설치합니다.

./wpt make-hosts-file | sudo tee -a /etc/hosts

MANIFEST.json을 생성합니다.

./wpt manifest

자세한 내용은 WPT의 설정 가이드를 참조하세요.

WPT 테스트 스위트 실행

wptrunner/ 디렉토리에 위치한 외부 Go 러너(runner)가 github.com/lightpanda-io/demo/ 저장소에서 제공됩니다. 먼저 프로젝트를 클론해야 합니다.

먼저 클론한 wpt/ 디렉토리에서 WPT의 HTTP 서버를 시작합니다.

./wpt serve

Lightpanda 브라우저를 실행합니다.

zig build run -- --insecure-disable-tls-host-verification

그 다음, demo를 클론한 디렉토리에서 wptrunner를 시작할 수 있습니다:

cd wptrunner && go run .

또는 특정 테스트 하나만 실행할 수 있습니다:

cd wptrunner && go run . Node-childNodes.html

wptrunner 명령어는 출력을 수정하는 --summary 및 --json 옵션을 허용합니다.
또한 --concurrency를 통해 동시성 제한 (concurrency limit)을 정의할 수 있습니다.

:warning: 전체 테스트 스위트 (test suite)를 실행하는 것은 매우 오래 걸릴 수 있습니다. 이 경우, 테스트 속도를 높이기 위해 ReleaseFast 모드로 빌드하는 것이 유용합니다.

zig build -Doptimize=ReleaseFast run

기여하기 (Contributing)

가이드라인은 CONTRIBUTING.md를 참조하세요.
풀 리퀘스트 (pull request) 과정에서 반드시 당사의 CLA에 서명해야 합니다.

• Discord

왜 Lightpanda인가?

현대적인 웹을 위해 Javascript 실행은 필수적입니다

과거에는 웹 자동화 (web automation)를 위해 단순한 HTTP 요청만으로도 충분했습니다. 하지만 이제는 그렇지 않습니다. 현재는 Javascript가 웹의 대부분을 구동합니다:

• Ajax, 싱글 페이지 애플리케이션 (Single Page Apps), 무한 스크롤 (infinite loading), 즉시 검색 (instant search)
• JS 프레임워크 (JS frameworks): React, Vue, Angular 및 기타

Chrome은 적절한 도구가 아닙니다

서버에서 전체 데스크톱 브라우저를 실행하는 것도 가능하지만, 확장성 (scale)이 좋지 않습니다. 수백 또는 수천 개의 인스턴스로 Chrome을 실행하는 것은 비용이 많이 듭니다:

• RAM 및 CPU 사용량이 높음
• 대규모 환경에서 패키징, 배포 및 유지보수가 어려움
• 헤드리스 (headless) 환경에서는 불필요한 기능이 많음

Lightpanda는 성능을 위해 구축되었습니다

실제 성능을 갖춘 Javascript 지원을 위해서는 Chromium을 포크 (fork)하는 대신 처음부터 새로 구축해야 했습니다:

• Chromium, Blink 또는 WebKit을 기반으로 하지 않음
• 명시적인 메모리 제어 (explicit memory control)가 가능한 저수준 언어 (low-level language)인 Zig로 작성됨
• 그래픽 렌더링 엔진 (graphical rendering engine)이 없음