프로그래밍
로컬 개발 서버, 네트워크 URL, 포트, 빌드, 정적 출력, 배포, 경고, 자주 보는 웹 오류를 이해하기 위한 검색형 참고 자료입니다.
42 개 항목
로컬 개발
localhost
http://localhost:3001브라우저나 명령어를 실행 중인 바로 그 컴퓨터 자신을 가리키는 호스트 이름입니다.
개발 서버가 실행 중인 같은 Mac 또는 PC에서 사이트를 확인할 때 사용합니다.
아이폰이나 아이패드의 localhost는 그 기기 자신을 뜻하므로 Mac의 localhost 주소로 접속할 수 없습니다.
http://localhost:3001localhost에서 로컬 사이트를 열고 새 참고 페이지를 확인해줘.
로컬 개발
127.0.0.1
http://127.0.0.1:3001현재 컴퓨터 자신을 가리키는 루프백 IP 주소입니다.
같은 기기에서 테스트할 때 localhost와 거의 같은 용도로 사용됩니다.
http://127.0.0.1:3001localhost가 제대로 연결되지 않으면 127.0.0.1로도 확인해줘.
로컬 개발
Dev server
npm run dev개발 중에 사용하는 서버입니다. 빠른 재빌드와 개발 전용 기능을 제공합니다.
사이트를 빌드하거나 배포하기 전에 변경사항을 미리 확인할 때 사용합니다.
개발 서버의 동작이 배포된 프로덕션 동작과 항상 완전히 같지는 않습니다.
npm run dev아이폰에서 확인할 수 있도록 개발 서버를 실행해줘.
로컬 개발
Port
http://localhost:3001한 컴퓨터 안에서 어떤 서버 프로세스가 연결을 받을지 구분하는 번호입니다.
한 서버가 3001 포트를 사용 중이면 다른 서버는 3002 같은 다른 포트를 써야 합니다.
http://localhost:30013001 포트가 이미 사용 중이면 개발 서버를 다른 포트로 실행해줘.
로컬 개발
Local URL
Local: http://localhost:3001개발 서버가 실행 중인 같은 기기에서 접속할 때 사용하는 주소입니다.
개발 중인 컴퓨터의 데스크탑 브라우저에서 확인할 때 사용합니다.
Local: http://localhost:3001개발 서버를 실행한 뒤 Local URL을 알려줘.
네트워크 접속
Network URL
Network: http://172.30.1.55:3001같은 네트워크의 다른 기기가 개발 서버에 접속할 때 사용하는 주소입니다.
같은 Wi-Fi의 아이폰, 아이패드, 다른 컴퓨터에서 사이트를 확인할 때 사용합니다.
개발 서버가 0.0.0.0처럼 네트워크 접근 가능한 host로 실행되어야 합니다.
Network: http://172.30.1.55:3001아이패드에서 테스트할 수 있도록 Network URL이 나오게 개발 서버를 실행해줘.
네트워크 접속
IP address
172.30.1.55네트워크에서 기기를 식별하는 숫자 주소입니다.
LAN IP를 사용하면 같은 Wi-Fi의 다른 기기가 내 개발 서버에 접속할 수 있습니다.
로컬 네트워크 IP는 Wi-Fi나 공유기 상태에 따라 바뀔 수 있습니다.
172.30.1.55외부 기기 테스트를 위해 allowedDevOrigins에 현재 LAN IP를 사용해줘.
네트워크 접속
Host
--hostname 0.0.0.0서버가 요청을 받기 위해 연결을 기다리는 주소입니다.
0.0.0.0으로 실행하면 같은 네트워크의 다른 기기에서 개발 서버에 접근할 수 있습니다.
--hostname 0.0.0.0휴대폰 테스트를 위해 개발 서버를 hostname 0.0.0.0으로 실행해줘.
네트워크 접속
Same network
Mac and iPhone on the same Wi-Fi보통 같은 Wi-Fi 공유기에 연결된 기기들을 뜻합니다.
네트워크 설정이 허용되어야 휴대폰이 Mac의 개발 서버에 접속할 수 있습니다.
Mac and iPhone on the same Wi-Fi사이트 문제를 디버깅하기 전에 아이폰과 Mac이 같은 네트워크에 있는지 확인해줘.
Next.js 동작
allowedDevOrigins
allowedDevOrigins: ['172.30.1.55']특정 출처가 Next.js 개발 리소스에 접근하도록 허용하는 개발용 설정입니다.
LAN IP로 아이폰이나 아이패드에서 Next 개발 서버를 확인할 때 필요할 수 있습니다.
이 설정은 개발용입니다. 배포된 정적 사이트는 같은 개발 리소스 접근 경로를 사용하지 않습니다.
allowedDevOrigins: ['172.30.1.55']개발 테스트를 위해 현재 LAN IP를 allowedDevOrigins에 추가해줘.
네트워크 접속
Cross-origin
Blocked cross-origin request프로토콜, 호스트, 포트 중 하나가 다른 출처 사이의 요청입니다.
개발 도구는 보안을 위해 개발 리소스에 대한 교차 출처 접근을 기본적으로 막을 수 있습니다.
Blocked cross-origin request이 교차 출처 경고가 실제 배포 사이트에도 영향을 주는지 설명해줘.
Next.js 동작
HMR
/_next/webpack-hmrHMR은 개발 중 브라우저 전체 새로고침 없이 변경사항을 반영하는 기능입니다.
HMR 개발 리소스가 차단되면 페이지는 로드되어도 개발 중 상호작용이나 스크립트가 이상하게 보일 수 있습니다.
HMR은 개발 전용이며 최종 정적 출력물에는 포함되지 않습니다.
/_next/webpack-hmr아이폰 문제가 HMR 개발 리소스 차단 때문에 생긴 것인지 확인해줘.
Next.js 동작
Turbopack
Next.js 16.2.5 (Turbopack)Next.js가 개발과 빌드 과정에서 사용하는 번들러입니다.
개발 서버나 빌드 출력에서 이 이름을 볼 수 있습니다.
Next.js 16.2.5 (Turbopack)Turbopack 출력 내용을 요약하고 빌드가 성공했는지 알려줘.
Next.js 동작
App Router
src/app/[locale]/reference/page.tsxapp 디렉터리를 기준으로 페이지 경로를 만드는 Next.js 라우팅 방식입니다.
폴더 아래에 page.tsx를 추가하면 해당 경로의 페이지가 만들어집니다.
src/app/[locale]/reference/page.tsxApp Router 폴더 구조에 맞춰 새 참고 페이지를 추가해줘.
Next.js 동작
generateStaticParams
generateStaticParams()빌드 시점에 어떤 동적 경로를 생성할지 알려주는 Next.js 함수입니다.
언어 페이지에서 /en, /ko, /ja 같은 언어별 경로를 만들 때 사용합니다.
generateStaticParams()새 참고 페이지가 모든 언어에 대해 generateStaticParams를 가지게 해줘.
빌드와 출력
Build
npm run build사이트를 프로덕션 또는 정적 출력물로 만들기 위해 컴파일하고 준비하는 과정입니다.
배포 전에 빌드를 실행하면 TypeScript, 경로, 정적 생성 문제를 잡을 수 있습니다.
npm run build빌드를 실행하고 새 경로가 생성되는지 확인해줘.
빌드와 출력
Lint
npm run lint코드 스타일, 정확성, 프레임워크 규칙 문제를 찾는 정적 검사입니다.
린트는 빌드나 커밋 전에 빠르게 확인하는 검사입니다.
npm run lint참고 페이지를 수정한 뒤 lint를 실행해줘.
빌드와 출력
Static export
output: "export"페이지를 실행 중인 서버 없이 정적 파일로 생성하는 빌드 출력 방식입니다.
정적 출력은 미리 만들어진 HTML, CSS, JavaScript 파일로 사이트를 호스팅할 때 유용합니다.
일부 서버 전용 기능은 정적 출력에서 동작하지 않습니다.
output: "export"새 페이지가 정적 출력과 호환되게 유지해줘.
빌드와 출력
SSG
● (SSG) prerendered as static HTMLSSG는 빌드 시점에 페이지를 미리 생성하는 방식입니다.
generateStaticParams가 있는 참고 페이지는 빌드 중 각 언어별로 생성됩니다.
● (SSG) prerendered as static HTML참고 페이지 경로가 빌드 출력에서 SSG로 표시되는지 확인해줘.
빌드와 출력
Prerender
prerendered as static content사용자가 요청하기 전에 보통 빌드 중에 페이지를 미리 렌더링하는 것입니다.
사전 렌더링된 페이지는 HTML이 이미 만들어져 있어 빠르게 로드됩니다.
prerendered as static content모든 언어 페이지가 사전 렌더링에 성공했는지 확인해줘.
빌드와 출력
Bundle
static JS bundle브라우저가 사용할 수 있도록 코드와 의존성을 묶어 컴파일한 파일입니다.
번들이 커지면 로드 속도에 영향을 줄 수 있으므로 사이트가 커질수록 주의해야 합니다.
static JS bundle단순 참고 페이지를 위해 무거운 라이브러리를 추가하지 말아줘.
배포
Deploy
deploy static output빌드된 사이트를 웹에서 사용자가 접속할 수 있게 게시하는 과정입니다.
배포는 로컬 확인, lint, build가 통과한 뒤 진행하는 것이 좋습니다.
deploy static output아직 배포하지 말고 페이지 준비와 빌드 확인까지만 해줘.
배포
Production
production deployment사용자가 실제로 접속하는 배포된 운영 환경입니다.
프로덕션에는 개발 전용 기능이 없으므로 로컬 개발 서버와는 다르게 확인해야 합니다.
production deployment이 경고가 프로덕션에도 영향을 주는지, 개발 환경에만 해당하는지 설명해줘.
배포
Hosting
static hosting provider배포된 사이트 파일을 저장하고 사용자에게 제공하는 서비스 또는 서버입니다.
서버 로직이 필요 없다면 정적 출력물은 정적 호스팅에서 제공할 수 있습니다.
static hosting provider출력물이 정적 호스팅에서 동작하도록 확인해줘.
배포
Domain
example.com사용자가 사이트에 접속하기 위해 입력하는 사람이 읽기 쉬운 주소입니다.
도메인은 DNS를 통해 배포된 호스팅 위치를 가리킵니다.
example.com프로덕션 도메인에서 동작해야 하는 링크에 localhost를 하드코딩하지 말아줘.
배포
DNS
A record / CNAME record도메인 이름을 서버나 호스팅 대상으로 연결하는 시스템입니다.
커스텀 도메인이 배포 사이트로 연결되려면 DNS 설정이 맞아야 합니다.
A record / CNAME record문제가 DNS 문제인지 앱 빌드 문제인지 설명해줘.
배포
Cache
clear browser cache페이지를 더 빠르게 로드하기 위해 저장해 둔 파일이나 응답의 복사본입니다.
배포 후에도 오래된 캐시 때문에 브라우저가 한동안 이전 버전을 보여줄 수 있습니다.
clear browser cache캐시 때문에 이전 페이지가 계속 보이는지 확인해줘.
실행 환경
Node.js
node --version개발 도구, 빌드 스크립트, 서버를 실행하는 JavaScript 실행 환경입니다.
Next.js dev와 build 명령은 Node.js 위에서 실행됩니다.
node --version이 경고가 Node.js, Next.js, 앱 코드 중 어디에서 나온 것인지 알려줘.
실행 환경
npm
npm run buildJavaScript 프로젝트에서 패키지 설치와 스크립트 실행에 자주 쓰는 도구입니다.
package.json에 정의된 dev, lint, build 같은 스크립트를 npm으로 실행할 수 있습니다.
npm run buildnpm build 스크립트를 실행하고 결과를 요약해줘.
실행 환경
package.json
"scripts": { "dev": "next dev -p 3001" }스크립트, 의존성, 패키지 정보를 정의하는 프로젝트 파일입니다.
프로젝트에서 어떤 명령을 실행해야 하는지 확인할 때 package.json을 봅니다.
"scripts": { "dev": "next dev -p 3001" }어떤 dev 명령을 실행할지 결정하기 전에 package.json을 확인해줘.
실행 환경
Environment variable
NEXT_PUBLIC_SITE_URL=https://example.com소스 코드 밖에서 앱이나 빌드 환경에 전달되는 값입니다.
환경 변수는 사이트 URL, API 키, 배포 환경별 설정에 사용됩니다.
비밀값은 클라이언트에 공개되는 환경 변수로 노출하면 안 됩니다.
NEXT_PUBLIC_SITE_URL=https://example.com프로덕션 사이트 URL용 환경 변수가 있다면 하드코딩하지 말아줘.
오류와 경고
404
404 Not Found요청한 페이지나 파일을 찾을 수 없다는 오류입니다.
경로가 삭제되었거나 이름이 바뀌었거나 정적 출력에서 생성되지 않았을 때 발생할 수 있습니다.
404 Not Found삭제 후 기존 programming-basics URL이 404를 반환하는지 확인해줘.
오류와 경고
500
500 Internal Server Error서버가 요청을 처리하는 중 실패했다는 오류입니다.
개발 중에는 터미널이나 브라우저 오버레이에서 원인 오류를 확인할 수 있습니다.
500 Internal Server Error500이 뜨면 터미널 오류를 보고 실패한 파일을 찾아줘.
오류와 경고
Module not found
Module not found: Can't resolve '@/lib/programming'import가 찾을 수 없는 파일이나 패키지를 가리킨다는 오류입니다.
파일을 이동, 삭제, 이름 변경한 뒤 import를 갱신하지 않았을 때 자주 발생합니다.
Module not found: Can't resolve '@/lib/programming'삭제된 파일을 아직 가리키는 import를 찾아 수정해줘.
오류와 경고
Export not found
Export programmingBasicsCopy doesn't exist파일은 있지만 요청한 이름의 export가 그 파일에 없다는 오류입니다.
데이터 객체 이름을 바꿨지만 import가 예전 이름을 계속 사용할 때 발생할 수 있습니다.
Export programmingBasicsCopy doesn't exist예전 export 이름을 새 이름으로 모든 곳에서 교체해줘.
오류와 경고
EADDRINUSE
listen EADDRINUSE: address already in use 0.0.0.0:3001요청한 호스트와 포트를 다른 프로세스가 이미 사용 중이라는 오류입니다.
다른 포트를 쓰거나, 의도적으로 교체하려면 기존 서버를 종료해야 합니다.
listen EADDRINUSE: address already in use 0.0.0.0:3001EADDRINUSE가 뜨면 어떤 포트가 사용 중인지 알려주고 다른 포트를 사용해줘.
오류와 경고
DeprecationWarning
[DEP0205] DeprecationWarning: module.register() is deprecated현재는 동작하지만 나중에 제거되거나 바뀔 수 있는 API를 사용 중이라는 경고입니다.
경고는 확인해야 하지만 항상 빌드를 막는 오류는 아닙니다.
[DEP0205] DeprecationWarning: module.register() is deprecated이 DeprecationWarning이 무시 가능한지 코드 수정이 필요한지 알려줘.
오류와 경고
Hydration
Hydration failed because the server rendered HTML didn't match클라이언트 JavaScript가 서버에서 렌더링된 HTML에 연결되는 과정입니다.
서버와 클라이언트가 처음 렌더링한 내용이 다르면 mismatch 오류가 발생할 수 있습니다.
Hydration failed because the server rendered HTML didn't match하이드레이션이 실패하면 어떤 컴포넌트가 클라이언트에서 다르게 렌더링되는지 확인해줘.
명령어
npm run dev
npm run dev로컬 개발 서버를 시작하는 프로젝트 스크립트입니다.
페이지를 수정하고 로컬에서 변경사항을 확인할 때 사용합니다.
npm run devnpm run dev를 실행하고 Local URL과 Network URL을 알려줘.
명령어
npm run build
npm run build프로덕션 빌드 또는 정적 출력물을 만드는 프로젝트 스크립트입니다.
변경 후 앱이 성공적으로 생성되는지 확인하기 위해 실행합니다.
npm run buildnpm run build를 실행하고 경고나 실패 내용을 요약해줘.
명령어
npm run lint
npm run lint린트 검사를 실행하는 프로젝트 스크립트입니다.
빌드 전에 실행하면 여러 코드 문제를 빠르게 잡을 수 있습니다.
npm run lint사이트를 빌드하기 전에 lint를 실행해줘.
명령어
curl
curl -I http://localhost:3001/koHTTP 요청을 보내고 응답을 확인하는 명령줄 도구입니다.
curl은 로컬 또는 배포 페이지가 200, 404 등 어떤 상태로 응답하는지 빠르게 확인할 수 있습니다.
curl -I http://localhost:3001/ko새 참고 경로가 200으로 응답하는지 curl로 확인해줘.