실행은(는) 무엇을 하나요?
사이트는 실제로 실행되었을 때 비로소 완성됩니다. 소스 코드는 의도를 알려주지만, 브라우저는 사용자가 실제로 얻는 결과를 보여줍니다. 이 스킬은 폴더에서 렌더링된 페이지까지의 가장 짧은 경로입니다.
실행하기
node <skill folder>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
--detect는 감지된 내용을 출력하고 아무것도 시작하지 않습니다. 폴더가 낯설 때 먼저 이 옵션을 사용하세요.--port는 해당 포트에서 시작하여 다음 빈 포트를 사용하므로 두 프로젝트를 동시에 실행할 수 있습니다.--open은 기본 브라우저를 엽니다.--shot out.png는 Playwright를 통해 1440px 너비, 전체 높이로 페이지를 렌더링합니다.--stop은.run/state.json에서 프로세스 트리를 종료합니다.
프로젝트 옆에 .run/state.json(pid, port, url, command)과 .run/server.log를 작성합니다. 이 두 파일이 시작과 중지 간의 전체 핸드오버입니다.
감지하는 내용
| 찾은 항목 | 실행 방식 |
|---|---|
dev, start, serve 또는 preview 스크립트가 있는 package.json | 빈 포트에서 npm run <해당 스크립트> 실행, PORT 설정 |
루트에 index.html | 해당 폴더에서 python -m http.server 실행 |
public/index.html, dist/index.html, build/index.html | 빌드된 출력을 루트로 하는 정적 서버 실행 |
| 설정 파일이 있지만 스크립트가 없는 경우 | 보고하고 중지: 프로젝트 자체 명령어가 필요함 |
go.mod, Cargo.toml, pubspec.yaml | 보고하고 중지: 프로젝트 자체 실행 명령어 사용 |
프레임워크별 세부 사항, 포트 기본값 및 알아야 할 실패 모드: references/stacks.md
결과 읽기
이 스크립트는 세 가지만 증명합니다: 프로세스가 시작되었음, 포트가 응답했음, 페이지가 렌더링되었음. 알 수 없는 것은:
- 375, 768, 1440px에서 레이아웃이 올바른지 (이를 위해서는
sitecraft/scripts/verify.mjs사용) - 콘솔이 깨끗한지 (여기서는 캡처되지 않음;
verify.mjs가 캡처) - 스크린샷이 사용자가 의도한 페이지인지 (URL이 요청한 경로와 일치하는지 확인)
따라서 루프는 다음과 같습니다: serve.mjs --shot 실행, 직접 이미지 확인, 수정, 다시 스크린샷. 한 번의 패스에서 최대 3번의 렌더링; 그 이상이면 문제는 CSS가 아니라 계획에 있습니다.
규칙
- 서버를 실행 중인 상태로 두지 마십시오. 확인이 끝나면 중지하거나, 여전히 실행 중이며 어떤 포트인지 명확히 알리십시오. 사용자 머신에 방치된 dev 서버는 사용자가 정리해야 할 혼란입니다.
- 중지할 수 없는 것은 시작하지 마십시오. 프로젝트에 Docker, 데이터베이스 또는 유료 API 키가 필요하다면, 실행 전에 반드시 알리십시오.
- 실제 URL을 보고하십시오. "앱"이 아닌
localhost:4173로 알리십시오. 4173이 사용 중이어서 포트가 변경되었다면 새 포트를 알리십시오. - 로그를 읽기 전에 추측하지 마십시오. 실패한 시작은 거의 항상 누락된 종속성, 누락된 환경 변수 또는 이미 사용 중인 포트 때문입니다.
.run/server.log에 답이 있으며, 실제 오류를 인용하는 것이 이론보다 낫습니다. - 설치를 알리지 않고 진행하지 마십시오.
node_modules가 누락된 경우npm install이 일반적으로 올바르며, 이는 프로젝트를 변경하는 작업입니다. 실행한 후 실행했다고 알리거나, 설치가 큰 경우 한 번 물어보십시오. - 프레임워크보다 정적 서버를 우선하십시오. 빌드된 출력이 존재하고 최신 상태라면,
dist/를 서빙하는 것이 dev 서버보다 빠르고 정확합니다.
시작되지 않는 경우
.run/server.log를 읽고 마지막 줄이 아닌 첫 번째 실제 오류를 인용하십시오.- 누락된 종속성: 프로젝트에서
npm install실행 후 재시도. - 누락된 환경 변수:
.env.example을 찾아 필요한 것을 명시하고, 값이 비밀이고 누락된 경우 중지. - 이미 사용 중인 포트: 스크립트는 이미 다음 빈 포트로 넘어가지만, 프레임워크 설정에 하드코딩된 포트가 원인인 경우가 일반적입니다.
- 빌드 단계 필요: 먼저
npm run build를 실행한 후dist/를 서빙하십시오. - 네이티브 또는 컨테이너화된 환경: 프로젝트 문서에 있는 명령어를 안내하십시오. 모든 스택이 스크립트로 처리되는 것은 아닙니다.
체크리스트
- 스택을 가정하지 않고 감지했음
- 시작 후 실제 HTTP 응답을 확인했음 (단순히 프로세스를 실행한 것만이 아님)
- 정확한 URL과 포트를 보고했음
- 로그뿐만 아니라 스크린샷도 확인했음
- 경로가 의도한 페이지와 일치하는지 확인했음
- 중지했거나, 여전히 실행 중이며 어디인지 알렸음
- 실패 시 실제 오류를 인용했음