로컬호스트(localhost) 뜻과 배포된 웹의 차이: NPM, NPX, 터미널 정리

AI로 쇼핑몰을 만들었는데 왜 나만 볼 수 있을까요?

AI에게 “쇼핑몰 하나 만들어줘”라고 부탁한 상황입니다. AI가 코드를 작성하고 “이제 localhost:3000에서 확인하세요”라고 말합니다. 브라우저 주소창에 http://localhost:3000을 넣으니 내가 만든 화면이 열립니다.

신이 나서 친구에게 같은 주소를 보냅니다. 친구는 “아무것도 안 뜨는데?”라고 답합니다. 나는 볼 수 있는데 친구는 못 보고, 터미널을 닫은 뒤에는 나도 다시 접속하지 못합니다.

친구에게 같은 주소를 보냈는데 화면이 열리지 않는 이유는 localhost가 각자의 기기를 가리키기 때문입니다. 내 컴퓨터에서 웹을 실행하는 것과 다른 사람이 접속하도록 제공하는 것은 별도 작업입니다.

로컬호스트(localhost)가 뭔가요?

로컬호스트는 주소를 여는 기기 자신을 가리키는 이름입니다. 내 노트북의 브라우저에서 열면 내 노트북을, 친구의 스마트폰에서 열면 친구의 스마트폰를 가리킵니다.

집 안에서 “안방으로 가자”라고 말하는 상황과 비교할 수 있습니다. 내 집에서 말하면 우리 집 안방을 가리키고 친구 집에서 말하면 친구 집 안방을 가리킵니다. 같은 말이어도 기준이 되는 집이 다릅니다. localhost도 주소를 사용하는 기기를 기준으로 합니다.

IP 주소는 네트워크에서 통신 대상을 구분할 때 쓰는 주소입니다. 자기 기기로 돌아오는 주소를 루프백(loopback) 주소라고 부르며 대표적으로 IPv4의 127.0.0.1과 IPv6의 ::1이 있습니다. 두 표기를 지금 외울 필요는 없습니다. localhost가 자기 기기를 가리킨다는 점부터 기억하면 됩니다. localhost의 표준 정의

http://localhost:3000을 나누어 보면 이렇습니다.

포트는 한 기기에서 여러 서비스를 구분하는 번호입니다. 집 비유로 돌아가면 찾아갈 문에 붙은 번호표에 해당합니다. 3000은 웹 전체가 정한 필수 번호가 아니며 프로젝트가 다른 번호를 사용할 수 있습니다.

localhost라는 이름이 서버를 켜 주지는 않습니다. 해당 포트에서 요청을 기다리는 서버 프로그램이 있어야 연결됩니다. 서버는 브라우저의 요청을 받고 페이지나 데이터를 돌려주는 프로그램입니다.

주소가 localhost이면 나만 볼 수 있나요?

localhost 주소 자체는 자기 기기를 가리키지만 서버의 접속 허용 범위는 별도입니다. 서버가 루프백 주소에서만 요청을 받도록 실행됐다면 다른 기기가 그 주소로 직접 접속할 수 없습니다. 반면 모든 네트워크 연결에서 요청을 받도록 실행했다면 같은 네트워크의 다른 기기에서 접속할 수도 있습니다. 방화벽 등 네트워크 조건도 영향을 줍니다. Node.js의 서버 접속 설정

따라서 주소창에 localhost가 보인다는 사실만으로 ‘아무도 접근할 수 없다’고 판단하지 않습니다. 개발 도구에 Network 주소가 보이거나 외부 공유 기능을 켰다면 그 범위를 확인해야 합니다. localhost 페이지가 API, 즉 프로그램끼리 요청을 주고받는 통로로 외부 AI 서비스나 데이터 저장소에 요청을 보내는 경우도 있습니다.

내 컴퓨터에서 실행하면 코드를 고치며 결과를 확인하기 편하고 웹을 제공할 서버 공간이나 실행 환경을 빌리는 호스팅 비용을 줄일 수도 있습니다. 다만 외부 API를 쓰면 그 사용료는 생길 수 있습니다. 로컬 실행이 모든 비용과 외부 전송을 없애 주지는 않습니다.

터미널, Node.js, npm, npx는 각각 무엇인가요?

이 네 용어는 JavaScript 기반 웹 프로젝트에서 자주 함께 나옵니다. 모든 웹사이트가 이 도구들을 요구하는 것은 아닙니다.

터미널: 명령을 입력하고 결과를 보는 창

터미널은 글자로 명령을 입력해 프로그램을 실행하고 결과를 보는 창입니다. 화면 색은 설정에 따라 다릅니다. 서버가 실행 중이어도 새 요청이 없으면 아무 글자도 추가되지 않을 수 있습니다. 로그는 프로그램의 실행 상태와 오류 등을 남긴 기록입니다. 새 로그가 없어도 서버가 정상적으로 요청을 기다리고 있을 수 있습니다.

Node.js: JavaScript를 실행하는 환경

JavaScript는 웹에서 많이 쓰는 프로그래밍 언어입니다. Node.js는 이 언어로 작성한 코드를 브라우저 밖에서 실행하는 환경입니다. 요리 비유에서는 코드를 실행할 수 있는 부엌에 해당합니다. 개발 서버를 실행할 때 Node.js를 요구하는 프로젝트가 많습니다. Node.js 소개

npm: 패키지를 설치하고 정해 둔 명령을 실행하는 도구

패키지는 다른 사람이 재사용할 수 있게 묶은 코드입니다. npm은 패키지를 설치하고 프로젝트에 등록된 명령을 실행하는 도구입니다. npm의 패키지 저장소를 재료 창고, 설치 명령을 장보기 도구라고 비유할 수 있습니다. 저장소와 내 컴퓨터에서 실행하는 명령은 서로 다른 대상입니다. npm 소개

package.json은 프로젝트 이름과 필요한 패키지, 실행 명령 등을 적는 파일입니다. npm install은 그 파일과 잠금 파일 등의 조건에 따라 필요한 패키지를 설치합니다. 설치한 코드가 보통 들어가는 node_modules 폴더는 재료를 보관하는 공간에 해당합니다.

npm run dev는 package.json의 scripts에 등록된 dev 명령을 실행합니다. 이름이 dev라고 모든 프로젝트에서 같은 서버가 실행되지는 않습니다. dev 항목이 없는 프로젝트에서는 이 명령이 실패합니다. npm run 설명

npx: 패키지의 명령을 실행하는 도구

npx는 패키지가 제공하는 실행 명령을 호출합니다. 이미 설치된 패키지를 사용할 수 있고, 필요한 패키지가 없으면 내려받아 npm 캐시에서 실행할 수 있습니다. 캐시는 다시 쓸 자료를 보관하는 공간입니다. 한 번 실행하고 반드시 삭제하는 도구는 아닙니다. npx 공식 설명

마지막 행의 <도구 이름>은 설명용 빈칸이며 그대로 실행하는 명령이 아닙니다. 설치와 실행은 실제 코드를 동작시키는 일이므로 프로젝트의 안내와 패키지 이름을 확인한 뒤 진행합니다.

먼저 로그에서 접속 주소를 찾아봅니다

아래는 특정 프로젝트를 실행한 결과가 아닌 가상 로그입니다. 설치 없이 읽는 연습부터 할 수 있습니다.

이 경우 브라우저에서 열 주소는 http://localhost:3001입니다. 글에서 3000을 예로 들었다고 3000으로 바꾸지 않습니다. 기기는 자기 기기, 포트는 3001이라고 나누어 설명할 수 있으면 주소를 읽은 것입니다.

같은 로그의 주소가 http://localhost:5173으로 바뀌었다면 어떤 주소를 열어야 할까요? 이번에는 5173을 포함한 주소 전체를 사용합니다. 두 주소 모두 친구의 기기에서는 친구 기기 자신을 가리킵니다.

이미 만든 연습 프로젝트를 실행한다면

아래는 현재 컴퓨터에서 직접 실행하는 연습입니다. Node.js와 npm이 준비돼 있고, 프로젝트 안내에 npm 사용과 dev 명령이 적혀 있는 경우에 해당합니다. 원격 개발 도구의 미리보기는 별도 주소나 포트 연결 기능을 사용할 수 있으므로 그 도구의 안내를 따릅니다. 아직 프로젝트가 없다면 앞의 로그 연습까지만 해도 됩니다. 터미널이 처음이라면 터미널 기초 설명을 먼저 읽습니다. Node.js 설치가 필요하면 프로젝트가 요구하는 버전을 확인하고 공식 다운로드 안내를 따릅니다.

1. 편집기에서 연습 프로젝트 폴더를 엽니다. VS Code를 쓴다면 File > Open Folder로 열고 Terminal > New Terminal을 선택할 수 있습니다. Mac과 Windows 모두 프로젝트 안의 package.json이 보이는지 확인합니다.
2. 터미널이 해당 폴더에서 열렸는지 확인합니다. Mac 터미널에서는 pwd, Windows PowerShell에서는 Get-Location으로 현재 경로를 볼 수 있습니다. 출력된 경로의 마지막 폴더 이름을 편집기에서 연 폴더와 비교합니다. 같은 이름의 폴더가 여러 곳에 있다면 전체 경로까지 대조합니다. 폴더가 다르면 프로젝트 폴더에서 터미널을 다시 엽니다.
3. node --version과 npm --version을 각각 실행합니다. 버전 번호가 나오고 프로젝트가 요구하는 버전과 맞는지 확인합니다. 명령을 찾을 수 없다는 오류가 나오면 설치 상태부터 해결합니다.
4. 프로젝트 README의 설치 안내를 따릅니다. README는 프로젝트 사용 설명 파일입니다. npm을 쓰며 아직 의존성을 설치하지 않은 프로젝트라면 안내에 따라 npm install을 실행합니다. 설치가 오류 없이 끝나기 전에 다음 명령을 이어서 실행하지 않습니다.
5. npm run dev를 실행하고 준비 완료 표시와 실제 접속 주소를 확인합니다. 그 주소 전체를 복사해 같은 컴퓨터의 브라우저 주소창에 넣습니다.
6. 예상한 프로젝트 화면이 열렸는지 확인합니다. 같은 포트에 다른 앱이 실행 중일 수도 있으므로 주소만 보고 성공했다고 판단하지 않습니다.

실행 상태를 확인한 뒤 서버를 실행한 터미널에서 Control 키를 누른 채 C를 누릅니다. Mac에서도 Command가 아닌 Control입니다. 이 동작은 보통 현재 터미널의 서버를 중지합니다. 종료 확인을 묻는 환경에서는 해당 프로그램의 안내를 따릅니다.

브라우저를 새로고침해 새 요청이 실패하는지 확인합니다. 이미 표시된 화면이 그대로 남거나 캐시된 내용이 보일 수 있어 화면이 남았다는 사실만으로 서버가 살아 있다고 판단하지 않습니다. 실행 터미널이 다시 명령을 받을 상태로 돌아왔는지도 봅니다.

마지막으로 같은 폴더에서 npm run dev를 다시 실행하고 새 로그의 주소로 접속합니다. 실행, 예상 화면 확인, 중지, 재실행까지 해보면 서버와 브라우저가 별도 프로그램이라는 점을 확인할 수 있습니다. 브라우저 탭만 닫는 것은 서버를 중지하는 동작이 아닙니다.

안 열릴 때는 어디부터 확인할까요?

포트가 겹치면 자동으로 다른 번호를 선택하는 도구도 있고 오류로 끝나는 도구도 있습니다. 로그에 3001이 표시됐다면 그 주소로 접속하고, 오류로 끝났다면 프로젝트의 포트 설정 안내를 확인합니다. 다른 작업의 서버를 무작정 종료하지 않습니다.

터미널 창을 닫으면 그 창에서 실행한 서버가 종료될 수 있습니다. 하지만 별도 프로세스로 실행하거나 원격 환경에서 실행한 서버는 계속 동작할 수 있습니다. 노트북 덮개를 닫았을 때도 절전 설정에 따라 달라집니다. 주소는 남아 있어도 응답할 서버가 멈추면 새 요청을 처리하지 못합니다.

다른 사람에게 보여주려면

배포는 다른 환경에서 사용할 수 있도록 파일과 실행 설정을 준비해 서비스를 제공하는 과정입니다. 내 노트북을 계속 켜 두지 않고 운영하려면 호스팅 서비스를 사용할 수 있습니다. 정적 페이지는 파일을 제공하는 방식으로, 서버 동작이 필요한 앱은 그에 맞는 실행 환경으로 배포합니다.

Vercel 같은 서비스는 Git 저장소를 연결하고 프로젝트를 구성하면 변경에 맞춰 배포할 수 있습니다. GitHub에 파일을 올리는 것만으로 모든 프로젝트가 자동 공개되지는 않습니다. 빌드 설정과 필요한 환경 변수, 접근 권한 등을 확인해야 합니다. Vercel 배포 안내

잠깐 보여줄 때는 같은 네트워크 공유나 터널을 사용할 수도 있습니다. 터널은 내 서버로 연결되는 별도 접속 경로를 만드는 방법입니다. 이때도 상대에게 전달할 주소와 허용할 사람을 정해야 합니다. 같은 Wi-Fi라는 이유만으로 localhost 주소를 공유할 수 있는 것은 아닙니다.

먼저 어느 기기의 어느 포트에 접속하는지, 그곳에서 어떤 서버가 실행 중인지 확인합니다. 이 두 항목을 확인하면 주소가 잘못됐는지, 서버가 꺼졌는지, 공유 설정이 필요한지 나누어 확인할 수 있습니다.