📦 Node 와 npm — 서버 개발의 시작점

왜 필요한가

지금까지 쓴 JavaScript 는 전부 브라우저 안에서 돌았다. 브라우저는 안전을 위해 JS 가 하드디스크를 읽거나 네트워크 포트를 여는 걸 막아둔다. 그래서 브라우저 JS 로는 서버를 만들 수 없다.

Node 는 JS 엔진(V8)을 브라우저에서 꺼내 컴퓨터 위에 올려놓은 것이다. 껍데기가 바뀌니 할 수 있는 일이 바뀐다. 파일을 읽고, 포트를 열고, DB 에 접속한다.

3장의 NestJS, 2장의 Next.js, 4장의 mysql2 — 전부 Node 위에서 돈다. 그 밑바닥을 오늘 30줄짜리 코드로 직접 만들어 본다. 오늘 만드는 5줄짜리 서버가 3장에서 NestJS 로 바뀌는 것뿐이다.

개념

브라우저 JS vs Node JS

Node 와 npm 과 node_modules

[내 프로젝트]
  package.json          ← "이 프로젝트가 뭘 쓰는지" 적은 명세서 (사람이 관리)
  package-lock.json     ← "정확히 어떤 버전을 깔았는지" 기록 (npm 이 관리)
  node_modules/         ← 실제 라이브러리 파일들 (git 에 안 올림)
        ▲
        │ npm install / npm ci 가 채운다
        │
  [npm 저장소 (인터넷)]

package.json 과 package-lock.json 은 git 에 올린다. node_modules/ 는 안 올린다(.gitignore).

node_modules 는 수만 개 파일에 수백 MB 다. 그래서 커밋하지 않고, 필요할 때 package-lock.json 을 보고 똑같이 복원한다. 9장에서 EC2 에 배포할 때 하는 일이 정확히 이것이다.

npm install vs npm ci

dependencies vs devDependencies

npm i mysql2              # dependencies    → 운영에서도 필요
npm i -D typescript       # devDependencies → 개발할 때만 필요

dependencies 는 운영에서도 돌아야 하는 것(@nestjs/core, mysql2, axios, next), devDependencies 는 빌드까지만 필요한 것(typescript, eslint, prettier, jest, @types/*)이다.

@types/node 처럼 타입 정의만 주는 패키지는 컴파일 후 사라지니 -D 로 넣는다.

ESM vs CJS 한 줄

CJS(CommonJS)는 require() / module.exports, ESM은 import / export 다. package.json 에 "type": "module" 을 넣거나 확장자를 .mjs 로 하면 ESM 이고, 아니면 CJS 다. NestJS 서버는 보통 CJS 로 빌드하고 Next.js 는 ESM 을 쓴다.

비동기 — 서버 코드는 전부 이거다

DB 조회, S3 업로드, 외부 API 호출 — 전부 "요청하고 답이 올 때까지 기다리는" 일이다. Node 는 기다리는 동안 다른 요청을 처리한다. 그래서 서버 코드에는 async 가 붙어 있다.

[동기]  주문 → 서서 기다림 → 받음 → 다음 손님        (한 명씩)
[비동기] 주문 → 진동벨 받고 자리로 → 다음 손님 주문 받음 → 벨 울리면 픽업

비동기를 표현하는 방식은 콜백(fs.readFile(p, (err, data) => ...)) → Promise(getUser(1).then().catch()) → async/await(const u = await getUser(1)) 순으로 발전했다. 지금은 세 번째만 쓴다.

await 은 "Promise 가 끝날 때까지 이 함수만 멈춰라"는 뜻이다. await 은 async 함수 안에서만 쓸 수 있다.

따라하기

1단계. Node 를 계산기처럼 써보기

node -e "console.log(1 + 1)"
node -e "console.log(process.version, process.platform)"
node -e "console.log(Object.keys(process.env).length + '개의 환경변수')"

-e 는 execute. 파일 없이 한 줄을 바로 실행한다. 4장에서 DB 연결을 빠르게 테스트할 때도 이걸 쓴다.

대화형으로 쓰려면 node 만 치면 된다. 나올 땐 Ctrl + D 또는 .exit.

2단계. 프로젝트 초기화

mkdir -p ~/Desktop/study/my-board/연습-node
cd ~/Desktop/study/my-board/연습-node
npm init -y
cat package.json

{
  "name": "연습-node",
  "version": "1.0.0",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  }
}

-y 는 "전부 기본값으로"다. 빼면 이름·버전을 하나씩 물어본다.

3단계. scripts 로 명령에 별명 붙이기

package.json 의 scripts 는 자주 치는 긴 명령에 짧은 별명을 붙이는 곳이다.

npm pkg set scripts.hello="node -e \"console.log('안녕 Node')\""
npm run hello

> 연습-node@1.0.0 hello
> node -e "console.log('안녕 Node')"

안녕 Node

참고 레포의 서버는 이렇게 생겼다.

start 와 test 만 npm start 처럼 run 없이 쓸 수 있고, 나머지는 전부 npm run 이름 이다.

4단계. 패키지 설치해 보기

npm i dayjs
npm i -D typescript
ls node_modules | head -5
cat package.json

dependencies 에 dayjs, devDependencies 에 typescript 가 들어갔는지 확인한다.

node -e "const d=require('dayjs'); console.log(d().format('YYYY-MM-DD HH:mm'))"

package-lock.json 도 같이 생겼다. ls -al 로 확인한다.

npm ci 도 체험해 본다.

rm -rf node_modules
npm ci
ls node_modules | wc -l

5단계. async/await 복습

cat > async-연습.js <<'EOF'
// 1초 뒤에 값을 주는 가짜 DB 조회
function findUser(id) {
  return new Promise((resolve, reject) => {
    setTimeout(() => {
      if (id === 0) reject(new Error('id 는 1 이상이어야 한다'));
      else resolve({ id, nickname: '보드지기' + id });
    }, 1000);
  });
}

async function main() {
  console.log('1. 시작');

  const user = await findUser(1);              // 여기서 1초 멈춘다
  console.log('2. 조회 결과:', user);

  // 여러 개를 동시에 — 총 1초면 끝난다 (순서대로 하면 3초)
  const users = await Promise.all([findUser(2), findUser(3), findUser(4)]);
  console.log('3. 동시 조회:', users.map((u) => u.nickname).join(', '));

  // 에러는 try/catch 로 잡는다
  try {
    await findUser(0);
  } catch (e) {
    console.log('4. 에러 잡음:', e.message);
  }

  console.log('5. 끝');
}

main();
EOF
node async-연습.js

1. 시작
2. 조회 결과: { id: 1, nickname: '보드지기1' }
3. 동시 조회: 보드지기2, 보드지기3, 보드지기4
4. 에러 잡음: id 는 1 이상이어야 한다
5. 끝

여기서 꼭 챙길 것 세 가지.

1. await 은 그 함수 안에서만 멈춘다. 서버 전체가 멈추는 게 아니다.
2. 독립적인 여러 작업은 Promise.all 로 동시에 돌린다. 3초가 1초가 된다.
3. 비동기 에러는 반드시 try/catch. 안 잡으면 unhandledRejection 으로 프로세스가 죽는다.

6단계. HTTP 서버를 5줄로 띄우기 — 오늘의 핵심

cat > 서버.js <<'EOF'
const http = require('http');
http
  .createServer((req, res) => res.end('hello my-board'))
  .listen(9100, () => console.log('http://localhost:9100 에서 대기 중'));
EOF
node 서버.js

http://localhost:9100 에서 대기 중

브라우저에서 http://localhost:9100 을 연다. hello my-board 가 보인다.
끄려면 터미널에서 Ctrl + C.

방금 무슨 일이 일어났나.

[브라우저]  GET http://localhost:9100/  ──▶  [9100 포트를 듣고 있는 node 프로세스]
                                                      │
                                              (req, res) 콜백 실행
                                                      │
[브라우저]  ◀── "hello my-board" (200 OK) ────────────┘

이게 서버의 전부다. 포트를 열고 → 요청이 오면 → 응답을 돌려준다. 3장의 NestJS 는 이 위에 라우팅·검증·의존성 주입을 얹은 것뿐이다.

7단계. 경로에 따라 다르게 응답하기 (JSON)

명세 5-2절의 GET /posts 흉내를 내본다.

cat > 서버.js <<'EOF'
const http = require('http');

const posts = [
  { id: 1, title: '첫 글', content: '안녕' },
  { id: 2, title: '둘째 글', content: '반갑다' },
];

const server = http.createServer((req, res) => {
  console.log(req.method, req.url);          // 요청 로그

  if (req.method === 'GET' && req.url === '/health') {
    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
    return res.end(JSON.stringify({ status: 'ok', uptime: process.uptime() }));
  }

  if (req.method === 'GET' && req.url === '/posts') {
    res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
    return res.end(JSON.stringify(posts));
  }

  res.writeHead(404, { 'Content-Type': 'application/json; charset=utf-8' });
  res.end(JSON.stringify({ statusCode: 404, message: 'Not Found' }));
});

server.listen(9100, () => console.log('9100 대기 중'));
EOF
node 서버.js

다른 터미널 탭(Command + T)에서 확인한다.

curl http://localhost:9100/posts
curl -i http://localhost:9100/health
curl -i http://localhost:9100/없는경로

-i 는 응답 헤더까지 보여준다. curl 은 다음 문서에서 제대로 다룬다.

여기서 이미 명세의 규칙 두 개를 지키고 있다. 응답을 { data: ... } 로 감싸지 않고 데이터를 직접 반환했고, 에러는 { statusCode, message } 형태다.

8단계. 코드를 고치면 자동 재시작 — --watch

지금은 코드를 고칠 때마다 Ctrl + C → node 서버.js 를 반복해야 한다. Node 18 부터는 기본 기능이 있다.

node --watch 서버.js

이제 서버.js 를 저장하면 자동으로 재시작된다.

예전부터 쓰던 도구인 nodemon 도 같은 일을 한다. 참고 레포와 우리 프로젝트는 NestJS 가 제공하는 nest start --watch(= npm run start:dev) 를 쓰므로 nodemon 을 따로 깔 일은 없다.

npm pkg set scripts.dev="node --watch 서버.js"
npm run dev

✅ 확인 — 이렇게 보이면 성공

터미널 A:

cd ~/Desktop/study/my-board/연습-node
node --watch 서버.js

터미널 B:

curl -s http://localhost:9100/posts
echo
curl -s -o /dev/null -w "%{http_code}\n" http://localhost:9100/없는경로

[{"id":1,"title":"첫 글","content":"안녕"},{"id":2,"title":"둘째 글","content":"반갑다"}]
404

터미널 A 에는 요청 로그가 쌓인다.

GET /posts
GET /%ec%97%86%eb%8a%94%ea%b2%bd%eb%a1%9c

브라우저 주소창에 http://localhost:9100/posts 를 넣으면 JSON 이 그대로 보인다.

🔧 흔한 에러

참고 레포에서 보기

📝 과제

1. 5줄 서버를 직접 띄우고 브라우저로 확인.
   연습-node/서버.js 를 만들어 9100 포트에서 hello my-board 를 응답한다.
   완료 조건: 브라우저 http://localhost:9100 에 문구가 뜨고, Ctrl + C 로 끄면 브라우저가 "연결할 수 없음"을 보여준다.

2. POST /posts 흉내 내기.
   7단계 서버에 분기를 추가한다. req.method === 'POST' && req.url === '/posts' 일 때 요청 본문을 읽어 posts 배열에 넣고 201 과 함께 새 글을 반환한다.
   힌트: 본문은 조각으로 온다.

   let body = '';
   req.on('data', (c) => (body += c));
   req.on('end', () => { const p = JSON.parse(body); /* ... */ });

   완료 조건: curl -X POST http://localhost:9100/posts -H 'Content-Type: application/json' -d '{"title":"세번째","content":"테스트"}' 가 201 과 새 글을 돌려주고, 이어서 curl http://localhost:9100/posts 에 3개가 보인다.

3. npm ci 와 npm i 의 차이 체감하기.
   rm -rf node_modules && time npm ci 와 rm -rf node_modules && time npm i 를 각각 실행해 걸린 시간을 비교하고, package-lock.json 을 일부러 지운 뒤 npm ci 를 돌려 어떤 에러가 나는지 확인한다.
   완료 조건: 두 명령의 차이를 학습일지에 두 줄로 적는다. (lock 파일은 npm i 로 복원한다)

🎯 요약 (3줄)

1. Node 는 브라우저 밖에서 JS 를 돌리는 껍데기다. http.createServer(...).listen(9100) 이면 이미 서버이고, NestJS 는 그 위에 얹힌 도구일 뿐이다.
2. package.json 은 명세서, package-lock.json 은 버전 고정 기록, node_modules 는 산출물이다. 개발은 npm i, 배포는 npm ci.
3. 서버 코드는 전부 비동기다. await 은 async 안에서만 쓰고, 독립 작업은 Promise.all 로 묶고, 에러는 반드시 try/catch 로 잡는다.

🌿 git 기초 — 첫 커밋부터 비밀키 보호까지

왜 필요한가

git 은 작업의 세이브 파일이다. 게임에서 보스 앞에 세이브하고 죽으면 되돌아가듯, 코드도 "여기까진 됐다" 지점을 찍어두고 언제든 돌아올 수 있다.

혼자 공부하는데 왜 필요한가? 세 가지 때문이다.

1. 되돌리기. 4장에서 DB 를 붙이다가 코드를 망가뜨렸을 때, 어제 커밋으로 1초 만에 돌아간다.
2. 배포. 9장에서 EC2 에 코드를 올리는 방법이 git clone 이다. git 이 없으면 배포 자체가 안 된다.
3. 비밀값 보호. .env 에 든 DB 비밀번호와 JWT 시크릿이 GitHub 에 올라가면 진짜 사고가 난다. 이걸 막는 게 .gitignore 다.

명세의 완료 조건 12번이 바로 이거다. ".env·비밀키가 git 에 한 번도 올라간 적 없다."

개념

git 의 3개 공간

[작업 폴더]          [스테이지]           [저장소(.git)]
 working tree        staging area          repository
     │                    │                     │
     │  git add ─────────▶│                     │
     │                    │  git commit ───────▶│
     │◀──────────────────────── git checkout ── │
     │                                          │
     └──────────── git push ───────────────────▶ [GitHub]

왜 add 와 commit 이 나뉘어 있나? 한 번에 여러 파일을 고쳤어도 "관련 있는 것만 골라서" 한 커밋으로 묶기 위해서다. add 는 고르는 행위, commit 은 저장하는 행위다.

파일의 4가지 상태

?? file.ts = untracked(git 이 모르는 새 파일), M file.ts = modified(내용만 바뀜), M file.ts(앞칸) = staged(add 해서 커밋 대기), 아무것도 안 보이면 committed.

브랜치

브랜치는 "평행 세계"다. 실무에선 기능마다 브랜치를 따지만, 이 스터디는 혼자 하니 main 하나로 충분하다. 브랜치를 나누는 건 12주 이후에 배워도 늦지 않다. 지금은 main 에 계속 커밋하는 게 더 빨리 완주하는 길이다.

따라하기

1단계. 저장소 만들기

mkdir -p ~/Desktop/study/my-board
cd ~/Desktop/study/my-board
git init
git status

Initialized empty Git repository in /Users/me/Desktop/study/my-board/.git/
On branch main

No commits yet

On branch main 이 나와야 한다. master 가 나오면 00-환경설정.md 의 git config --global init.defaultBranch main 을 빠뜨린 것이다. 지금 고치려면:

git branch -M main

2단계. .gitignore 부터 만든다 — 순서가 중요하다

cat > .gitignore <<'EOF'
# ── 의존성 ──
node_modules/

# ── 빌드 산출물 ──
dist/
.next/
out/
build/
*.tsbuildinfo

# ── 비밀값 (가장 중요) ──
.env
.env.local
.env.development
.env.production
*.pem
*.key

# 값이 없는 템플릿은 팀이 봐야 하므로 예외로 추적한다
!.env.example

# ── 로그 ──
logs/
*.log
npm-debug.log*

# ── macOS / 에디터 ──
.DS_Store
.idea/
.vscode/*
!.vscode/extensions.json

# ── 테스트 ──
coverage/
EOF
cat .gitignore

.env 는 막고 .env.example 은 올리는 이 조합이 실무 표준이다. 명세 8절의 환경변수 목록이 바로 .env.example 의 내용이 된다.

3단계. 첫 커밋

cat > README.md <<'EOF'
# my-board

풀스택 완주 프로젝트. Next.js(3100) + NestJS/Fastify(9100) + MySQL(my_board).
EOF

git status
git add .gitignore README.md
git status
git commit -m "chore: 프로젝트 초기화 (.gitignore, README)"
git log --oneline

a1b2c3d chore: 프로젝트 초기화 (.gitignore, README)

4단계. 커밋 메시지 규칙

참고 레포들처럼 앞에 종류를 붙인다. feat:(새 기능) fix:(버그) chore:(설정·잡일) refactor:(정리) docs:(문서) test:(테스트).

git commit -m "feat: posts 목록 API 추가"

한글로 써도 된다. 중요한 건 "무엇을 왜 바꿨는지"가 보이는 것이다. 수정, ㅇㅇ, asdf 같은 메시지는 3주 뒤의 자신을 괴롭힌다.

5단계. 상태 확인 3종 세트

echo "추가 줄" >> README.md

git status              # 뭐가 바뀌었나
git status -sb          # 짧게 (실무에서 이걸 더 많이 쓴다)
git diff                # 아직 add 안 한 변경 내용
git add README.md
git diff --staged       # add 한 변경 내용
git log --oneline --graph --decorate -10

6단계. GitHub 원격에 올리기

GitHub 에서 New repository → 이름 my-board → Private 선택 → README·gitignore 는 추가하지 않음(이미 우리가 만들었다) → Create.

그다음 나오는 주소를 쓴다. HTTPS 대신 SSH 방식을 권한다. 매번 비밀번호를 안 물어본다.

# SSH 키가 없으면 한 번만 만든다
ls ~/.ssh/id_ed25519.pub || ssh-keygen -t ed25519 -C "본인이메일@example.com"
cat ~/.ssh/id_ed25519.pub

출력된 ssh-ed25519 AAAA... 전체를 복사해서 GitHub → 우측 상단 프로필 → Settings → SSH and GPG keys → New SSH key 에 붙여 넣는다.

ssh -T git@github.com          # "Hi 아이디! You've successfully authenticated" 가 나오면 성공
git remote add origin git@github.com:본인아이디/my-board.git
git remote -v
git push -u origin main

-u 는 "앞으로 git push 만 쳐도 여기로 보내"라는 뜻이다. 한 번만 붙이면 된다.

7단계. 실수 복구 3가지

git 의 진짜 가치는 여기 있다.

(1) 파일을 망가뜨렸다. 마지막 커밋 상태로 되돌리고 싶다.

echo "망가뜨림" > README.md
git status
git restore README.md          # 최신 문법
# git checkout -- README.md    # 예전 문법. 같은 동작
cat README.md

(2) 커밋을 했는데 메시지가 틀렸거나 파일을 빠뜨렸다.

git commit --amend -m "chore: 프로젝트 초기화 (.gitignore, README, 포트 메모)"

(3) 커밋을 통째로 취소하고 싶다.

git reset --soft HEAD~1     # 커밋만 취소. 변경 내용은 스테이지에 그대로 (가장 안전)
git reset --mixed HEAD~1    # 커밋+add 취소. 변경 내용은 작업 폴더에 남음 (기본값)
git reset --hard HEAD~1     # 커밋+변경 내용까지 전부 삭제 (위험)

(4) 최후의 보험: reflog. --hard 로 날려도 살릴 수 있다. git 은 모든 HEAD 이동을 기록한다. git reflog 로 돌아갈 지점의 해시를 찾아 git reset --hard <해시>.

8단계. 비밀키를 커밋해 버렸을 때

가장 중요한 절이다. 5장에서 JWT_SECRET, 6장에서 AWS 키를 다루니 언젠가 겪는다.

상황 A. 아직 커밋 안 했다 (git status 에만 보임)

git restore --staged .env     # 스테이지에서 빼고
echo ".env" >> .gitignore     # .gitignore 에 추가
git status                    # .env 가 목록에서 사라졌는지 확인

상황 B. 커밋은 했지만 push 는 안 했다

git reset --soft HEAD~1       # 커밋 취소
git restore --staged .env     # 스테이지에서 제외
echo ".env" >> .gitignore
git add .gitignore
git commit -m "chore: .env 를 gitignore 에 추가"
git log -p | grep -c "JWT_SECRET"    # 0 이 나와야 한다

상황 C. 이미 push 했다

순서를 지킨다. 1번을 먼저 한다.

1. 값을 즉시 무효화한다 (가장 먼저).
   • JWT_SECRET → 새 값으로 교체. 기존 토큰은 전부 무효가 된다 (정상)
   • AWS 키 → AWS 콘솔 → IAM → 사용자 → 보안 자격 증명 탭 → 해당 액세스 키 비활성화 후 삭제 → 새 키 발급
   • DB 비밀번호 → RDS 또는 MySQL 에서 변경
2. 추적에서 제외한다.

   git rm --cached .env          # 파일은 남기고 git 추적만 해제
   echo ".env" >> .gitignore
   git commit -m "chore: .env 추적 제외"
   git push

3. 이력에서도 지운다 (선택이지만 권장). brew install git-filter-repo 후 git filter-repo --invert-paths --path .env --force → git remote add origin ... → git push --force origin main. 모든 커밋 해시가 다시 만들어지므로, 협업 중이라면 팀 전원이 다시 clone 해야 한다.
4. 검증한다.

   git log -p | grep -i "JWT_SECRET\|AWS_SECRET\|password" | head

   빈 결과면 끝. 이게 명세 완료 조건 12번이다.

예방책 — 커밋 전에 막기

.git/hooks/pre-commit 에 간단한 검사를 넣어두면 사고 자체를 막는다.

cat > .git/hooks/pre-commit <<'EOF'
#!/bin/sh
if git diff --cached --name-only | grep -qE '(^|/)\.env$|\.pem$|\.key$'; then
  echo "중단: .env / .pem / .key 가 커밋에 포함되어 있다."
  echo "git restore --staged <파일> 로 제외한 뒤 다시 커밋한다."
  exit 1
fi
EOF
chmod +x .git/hooks/pre-commit

이제 .env 를 실수로 add 해도 커밋이 막힌다.

확인 — 이렇게 보이면 성공

cd ~/Desktop/study/my-board
git add -A && git commit -qm "docs: README 보강"   # 5단계에서 고친 것 먼저 정리
echo "SECRET=1234" > .env        # 일부러 비밀 파일을 만들어 본다
git status -sb

## main...origin/main

git check-ignore -v .env

.gitignore:12:.env	.env

".gitignore 12번째 줄 때문에 무시된다"는 뜻이다. 커밋 이력도 확인한다.

git log --oneline
git remote -v

b2c3d4e docs: README 보강
a1b2c3d chore: 프로젝트 초기화 (.gitignore, README)
origin	git@github.com:본인아이디/my-board.git (fetch)
origin	git@github.com:본인아이디/my-board.git (push)

🔧 흔한 에러

참고 레포에서 보기

📝 과제

1. my-board 저장소 완성. git init → .gitignore 작성 → README.md 작성 → 첫 커밋 → GitHub private 저장소에 push. 완료 조건: GitHub 웹에서 저장소를 열었을 때 README.md 와 .gitignore 두 파일만 보인다. (주차 플랜 1주차 완료 조건에 해당)
2. .gitignore 동작을 직접 증명하기. echo "JWT_SECRET=abcd" > .env 로 파일을 만든 뒤 git status 에 안 나오는 것을 확인하고, git check-ignore -v .env 로 몇 번째 줄 규칙 때문인지 출력한다. 완료 조건: git add . 을 실행해도 .env 가 스테이지에 안 담긴다.
3. 복구 리허설. README.md 를 3번 고쳐 3개의 커밋을 만든다. 그다음 ① git restore 로 저장 안 한 변경 버리기, ② git commit --amend 로 메시지 고치기, ③ git reset --soft HEAD~1 로 커밋 취소 후 재커밋을 각각 해본다. 마지막에 git reflog 를 열어 지금까지의 이동 이력을 읽는다. 완료 조건: 세 가지를 전부 실행했고, git log --oneline 이 의도한 커밋 3개를 보여준다.

🎯 요약 (3줄)

1. git add(고르기) → git commit(저장) → git push(백업) 세 박자. 커밋 전엔 git diff --staged 로 무엇이 담겼는지 반드시 본다.
2. .gitignore 는 파일을 만들기 전에 먼저 만든다. node_modules, .next, dist, .env 는 무조건 제외하고 .env.example 만 예외로 올린다.
3. 비밀키를 올렸다면 지우기보다 값 교체가 먼저다. 실수는 git restore / git commit --amend / git reset --soft 로 대부분 복구되고, 최후엔 git reflog 가 있다.

🖥️ 터미널 완전 정복 치트시트 (프론트 개발자를 위한 20개 명령어)

왜 터미널이 필요한가

터미널은 컴퓨터에게 말로 시키는 창구입니다. 마우스가 "메뉴에서 골라 클릭"이라면, 터미널은 "이거 해"라고 문장으로 말하는 것이에요.

프론트만 하던 사람은 npm run dev 정도만 치고 살았을 겁니다. 그런데 AWS 서버(EC2)에 접속하면 화면이 없습니다. 마우스도 없어요. 검은 화면에 글자뿐입니다. 거기서 파일을 옮기고 프로그램을 띄우고 로그를 봐야 합니다.

개념부터 잡기

폴더 구조와 "현재 위치"

터미널에는 항상 "지금 내가 서 있는 폴더"가 있습니다. 이걸 현재 작업 디렉터리(cwd) 라고 불러요.

/                                 ← 루트. 모든 것의 꼭대기
├── Users/
│   └── me/                       ← 홈 디렉터리. 줄여서 ~
│       └── Desktop/
│           └── study/
│               └── my-board/     ← 여기에 서 있다면
│                   ├── web/      ← cd web      (상대 경로)
│                   └── server/   ← cd ./server (같은 뜻)
└── etc/

절대 경로 vs 상대 경로

cd ../server 는 "한 칸 위로 갔다가 server 로 들어가"라는 뜻입니다.

명령어 한 줄의 구조

  ls        -al      ~/Desktop
  │          │          │
  명령     옵션      대상(인자)

옵션은 - 하나에 한 글자(-a), -- 두 개에 단어(--help) 형태입니다. -al 은 -a -l 을 붙여 쓴 것이에요.

직접 따라해 보기

1단계. 위치 파악과 이동

pwd                 # 지금 어디 있나 (print working directory)
cd ~                # 홈으로
cd ~/Desktop/study
pwd
cd ..               # 한 칸 위
cd -                # 직전에 있던 곳으로 되돌아가기

cd 만 치고 Enter 해도 홈으로 갑니다.

2단계. 목록 보기

ls                  # 이름만
ls -l               # 자세히 (권한·크기·수정일)
ls -a               # 숨김 파일(.env, .gitignore)까지
ls -al              # 둘 다. 제일 많이 쓴다
ls -lh              # 크기를 1.2K, 3.4M 처럼 읽기 좋게

3단계. 만들기

cd ~/Desktop/study
mkdir 연습                       # 폴더 하나
mkdir -p 연습/a/b/c              # 중간 폴더까지 한 번에 (-p = parents)
cd 연습
touch memo.txt                   # 빈 파일 만들기
ls -al

4단계. 파일에 글 쓰고 읽기

echo "첫 줄이다" > memo.txt      # >  : 덮어쓰기
echo "둘째 줄이다" >> memo.txt   # >> : 이어붙이기
cat memo.txt                     # 전체를 한 번에 출력

첫 줄이다
둘째 줄이다

파일이 길면 cat 은 화면을 넘겨버립니다. 이럴 땐 less 를 쓰세요.

less memo.txt

less 안에서는:

5단계. 복사 · 이동 · 삭제

cp memo.txt memo-backup.txt      # 복사
cp -r a a-copy                   # 폴더 복사는 -r (recursive)
mv memo-backup.txt 백업.txt       # 이름 바꾸기
mv 백업.txt a/                    # 옮기기 (대상이 폴더면 이동)
rm a/백업.txt                     # 파일 삭제
rm -r a-copy                     # 폴더 삭제

rm -rf /        # 컴퓨터를 날린다
rm -rf ~        # 홈 폴더를 통째로 날린다

안전하게 쓰려면 rm -i (하나씩 물어봄) 를 쓰거나, 지우기 전에 ls 로 먼저 확인하는 습관을 들이세요.

6단계. Tab 자동완성과 Ctrl 단축키

cd ~/Desk        # 여기서 Tab → cd ~/Desktop/ 으로 완성됨
cat me           # Tab → cat memo.txt

Tab 을 눌렀는데 아무 일도 없으면 후보가 여러 개라는 뜻입니다. Tab 을 한 번 더 누르면 후보 목록이 떠요.

7단계. 파이프 | 와 리다이렉트 >

파이프는 앞 명령의 출력을 뒤 명령의 입력으로 넘기는 관입니다.

[ls -al]  ──출력──▶  |  ──입력──▶  [grep .env]  ──▶ 화면

ls -al | grep env          # 목록 중 env 가 들어간 줄만
cat memo.txt | wc -l       # 줄 수 세기
ls -al > 목록.txt           # 화면 대신 파일로 저장
ls -al | grep txt > 결과.txt

wc -l 은 줄 수, wc -c 는 글자 수를 셉니다.

8단계. grep — 내용 검색

grep 은 "이 글자가 들어간 줄을 찾아줘"입니다. 서버 로그에서 에러를 찾을 때 매일 써요.

grep "둘째" memo.txt                     # 파일 안에서 찾기
grep -n "둘째" memo.txt                  # 줄 번호까지 (-n)
grep -i "DULJJAE" memo.txt               # 대소문자 무시 (-i)
grep -r "PORT" ~/Desktop/.../01-basics   # 폴더 전체 재귀 (-r)

실무에서는 이렇게 씁니다.

pm2 logs --lines 200 | grep -i error     # 최근 로그에서 에러만

9단계. 프로세스와 포트 — 서버 공부 내내 쓴다

우리 서버는 9100 포트, 프론트는 3100 포트를 씁니다. 서버 공부를 시작하면 이런 에러를 반드시 만나요.

Error: listen EADDRINUSE: address already in use :::9100

"9100 을 이미 누가 쓰고 있다"는 뜻입니다. 범인을 찾아서 종료해야 해요.

lsof -i :9100          # 9100 포트를 쓰는 프로세스 찾기

COMMAND   PID     USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
node    54321 me         24u  IPv6 0x1a2b3      0t0  TCP *:9100 (LISTEN)

PID(프로세스 번호) 54321 이 범인입니다.

kill 54321             # 정중하게 종료 요청 (권장)
kill -9 54321          # 말을 안 들으면 강제 종료

한 줄로 끝내려면:

lsof -ti :9100 | xargs kill -9

-t 는 PID 만 출력하는 옵션이고, xargs 는 그 값을 뒤 명령의 인자로 넘깁니다.

현재 돌고 있는 프로세스를 보는 명령도 알아두세요.

ps aux | grep node                  # node 로 돌고 있는 것들
ps aux | grep -v grep | grep node   # grep 자기 자신은 빼고

10단계. ssh 맛보기

ssh 는 다른 컴퓨터의 터미널을 내 터미널에서 쓰는 것입니다. AWS EC2 에 접속할 땐 이렇게 생겼어요.

ssh -i ~/.ssh/my-board-key.pem ubuntu@3.36.12.34

접속하면 프롬프트가 me@맥북 % 에서 ubuntu@ip-172-31-x-x:~$ 로 바뀝니다. 이때부터 치는 명령은 전부 AWS 컴퓨터에서 실행돼요. 나올 때는 exit.

✅ 확인 — 이렇게 나오면 성공

아래를 순서대로 치고 마지막 출력이 일치하면 성공입니다.

cd ~/Desktop/study
mkdir -p 연습/로그
cd 연습
printf 'INFO 시작\nERROR DB 연결 실패\nINFO 종료\n' > 로그/app.log
grep -n ERROR 로그/app.log
cat 로그/app.log | wc -l

2:ERROR DB 연결 실패
       3

포트 확인도 해봅니다. 아무것도 안 띄운 상태라면 결과가 비어 있는 게 정상이에요.

lsof -i :9100
echo "종료코드: $?"

종료코드: 1

($? 는 직전 명령의 종료 코드입니다. 0 이면 성공, 0 이 아니면 실패/결과 없음.)

🔧 흔한 에러 해결

📝 과제

과제 1. 연습 문제 10개 (전부 터미널로)

~/Desktop/study/연습 폴더 안에서 풉니다. 답은 직접 명령을 만들어 내세요.

1. 지금 서 있는 폴더의 절대 경로를 출력하라.
2. 연습 안에 drill/a/b 폴더를 한 줄 명령으로 만들어라.
3. drill/a/b 안에 hello.txt 를 만들고 hello world 를 써 넣어라 (touch 없이 한 줄로).
4. hello.txt 에 second line 을 기존 내용을 지우지 않고 추가하라.
5. hello.txt 를 drill/a 로 복사하고, 원본은 greeting.txt 로 이름을 바꿔라.
6. 연습 아래에서 line 이 들어간 파일을 줄 번호와 함께 전부 찾아라 (재귀).
7. 연습 의 파일 목록을 목록.txt 로 저장하되, 숨김 파일도 포함하라.
8. 목록.txt 가 몇 줄인지 파이프를 써서 세어라.
9. 지금 내 맥에서 3100 포트를 쓰는 프로세스가 있는지 확인하고, 있으면 PID 를 찾아 종료하라.
10. drill 폴더를 통째로 삭제하라. 단, 삭제 전에 ls -R drill 로 먼저 확인하라.

과제 2. 포트 점유 상황을 일부러 만들고 해결하기

터미널 A 에서 아래를 실행해 9100 을 점유시킵니다.

node -e "require('http').createServer((q,s)=>s.end('hi')).listen(9100, ()=>console.log('9100 점유중'))"

터미널 B(Command + T)에서 같은 명령을 다시 실행해 EADDRINUSE 를 직접 봅니다. 그다음 터미널 B 에서 lsof -i :9100 으로 PID 를 찾아 kill 로 종료하세요.

과제 3. 나만의 alias 3개 만들기

~/.zshrc 에 자주 쓸 단축어 3개를 추가합니다. 예: alias p9='lsof -i :9100'.

🎯 요약 (3줄)

1. pwd(어디) → ls -al(뭐가 있나) → cd(이동) 세 개가 터미널의 90%입니다. 나머지는 Tab 과 ↑ 로 칩니다.
2. | 는 앞 출력을 뒤로 넘기는 관, > 는 덮어쓰기, >> 는 이어쓰기입니다. grep 과 조합하면 로그에서 에러만 뽑아냅니다.
3. 서버 공부 중 EADDRINUSE 가 뜨면 lsof -i :9100 으로 범인을 찾고 kill 로 끝냅니다. 이 한 세트를 계속 씁니다.