운영하기 2026년 5월 7일 수정일 2026년 5월 7일

새 Mac에서 Astro 블로그 작업 환경 이어서 세팅하기

기존에 운영하던 Astro 블로그를 새 Mac에서 이어서 작업하기 위해 Homebrew, Git, Node.js, VS Code, GitHub 인증, 저장소 clone, .env 복원, 빌드, 배포 확인까지 진행하는 과정을 정리합니다.

#Astro #macOS #GitHub #VSCode #블로그운영

들어가며

기존에 chailmon.com 블로그를 만들고 운영하면서, 새 컴퓨터에서도 같은 작업을 이어갈 수 있는 환경을 만드는 것이 중요하다는 걸 느꼈다.

Windows PC에서 블로그 작업 환경을 세팅하는 글을 먼저 작성했기 때문에, 이번에는 Mac에서 같은 Astro 블로그 작업 환경을 이어서 세팅하는 과정을 정리한다.

최종 목표는 다음과 같다.

1. Mac에서 기본 개발 도구 확인
2. Homebrew 설치 여부 확인
3. Git 설치 및 GitHub 인증 준비
4. Node.js와 npm 설치
5. VS Code 설치와 code 명령어 설정
6. GitHub 저장소 clone
7. .env 파일 복원
8. 로컬 개발 서버 실행
9. npm run build 테스트
10. GitHub push와 Cloudflare 자동 배포 확인

1. Mac 기본 터미널 준비

Mac에서는 기본 Terminal 앱을 사용해도 되고, iTerm2 같은 별도 터미널을 사용해도 된다.

나는 기본 Terminal 또는 VS Code 내장 터미널을 기준으로 작업한다.

터미널을 열고 현재 셸을 확인한다.

echo $SHELL

대부분의 최신 macOS에서는 아래처럼 나온다.

/bin/zsh

앞으로 명령어는 zsh 기준으로 진행한다.

2. Homebrew 설치 확인

Mac에서 개발 도구를 설치할 때는 Homebrew를 사용하면 편하다.

먼저 Homebrew가 설치되어 있는지 확인한다.

brew --version

버전이 출력되면 이미 설치된 상태다.

만약 설치되어 있지 않다면 Homebrew 공식 사이트의 설치 명령어를 사용하면 된다.

https://brew.sh

설치 후에는 터미널을 새로 열고 다시 확인한다.

brew --version

Homebrew가 정상적으로 동작하면 이후 Git, Node.js 같은 도구를 설치하거나 관리하기 쉬워진다.

3. Git 설치 및 확인

Mac에는 기본 Git이 설치되어 있는 경우가 많다.

먼저 확인한다.

git --version

정상적으로 버전이 나오면 Git을 사용할 수 있다.

Homebrew로 Git을 설치하거나 최신 버전으로 관리하고 싶다면 다음 명령어를 사용할 수 있다.

brew install git

설치 후 다시 확인한다.

git --version

4. Git 기본 사용자 정보 설정

GitHub에 커밋을 올리기 위해 Git 사용자 정보를 설정한다.

git config --global user.name "chailmon"
git config --global user.email "chailmon@outlook.com"

기본 브랜치 이름도 main으로 설정한다.

git config --global init.defaultBranch main

설정 확인은 다음 명령어로 한다.

git config --global --list

아래와 비슷하게 나오면 된다.

user.name=chailmon
user.email=chailmon@outlook.com
init.defaultbranch=main

5. Node.js와 npm 설치

Astro 블로그를 실행하려면 Node.js와 npm이 필요하다.

먼저 설치 여부를 확인한다.

node -v
npm -v

버전이 출력되면 설치되어 있는 상태다.

설치되어 있지 않다면 Homebrew로 설치할 수 있다.

brew install node

설치 후 다시 확인한다.

node -v
npm -v

기존 환경에서는 Node.js v25.9.0, npm 11.12.1을 사용했지만, 새 Mac에서는 안정적인 LTS 버전을 사용해도 된다.

중요한 것은 npm run dev와 npm run build가 정상 동작하는지다.

6. VS Code 설치와 code 명령어 설정

블로그 글 작성과 코드 관리는 Visual Studio Code에서 하는 것이 가장 편하다.

VS Code를 설치한 뒤, 터미널에서 프로젝트를 바로 열 수 있도록 code 명령어를 등록한다.

VS Code를 실행한 뒤 Command Palette를 연다.

Shift + Command + P

그리고 아래 명령어를 검색해서 실행한다.

Shell Command: Install 'code' command in PATH

터미널을 새로 열고 확인한다.

code --version

버전이 출력되면 정상이다.

이제 프로젝트 폴더에서 아래 명령어로 VS Code를 열 수 있다.

code .

7. VS Code 확장 설치

Astro 블로그 작업을 위해 아래 확장을 설치했다.

Astro
Tailwind CSS IntelliSense
MDX
Prettier - Code formatter

각 확장의 역할은 다음과 같다.

Astro
→ .astro 파일 문법 강조와 자동완성

Tailwind CSS IntelliSense
→ Tailwind CSS 클래스 자동완성

MDX
→ .mdx 글 작성 시 문법 강조

Prettier
→ 코드와 문서 포맷 정리

처음에는 필수 확장만 설치해도 충분하다.

8. 작업 폴더 만들기

블로그 프로젝트를 저장할 폴더를 만든다.

나는 다음 경로를 기준으로 사용한다.

mkdir -p ~/Dev/projects
cd ~/Dev/projects

프로젝트를 다른 경로에 두고 싶다면 원하는 위치를 사용해도 된다.

예를 들어 다음처럼 사용할 수 있다.

mkdir -p /Users/ib10500014/Developer/projects
cd /Users/ib10500014/Developer/projects

중요한 것은 이후 명령어에서 같은 경로를 계속 사용하는 것이다.

9. GitHub 저장소 clone

GitHub에 있는 기존 블로그 저장소를 내려받는다.

git clone https://github.com/chailmon/chailmon-blog.git
cd chailmon-blog

clone 후 상태를 확인한다.

git status

정상이라면 아래와 비슷하게 나온다.

현재 브랜치 main
브랜치가 'origin/main'에 맞게 업데이트된 상태입니다.
작업 폴더 깨끗함

영어 환경에서는 이렇게 보일 수 있다.

On branch main
Your branch is up to date with 'origin/main'.
nothing to commit, working tree clean

10. GitHub 인증 방식

HTTPS 방식으로 clone했다면 처음 push할 때 GitHub 인증이 필요할 수 있다.

가장 단순한 방식은 push 시 뜨는 GitHub 인증 창을 따라 로그인하는 것이다.

만약 인증이 반복해서 꼬이면 GitHub CLI를 설치해서 로그인하는 방법도 있다.

brew install gh
gh auth login

하지만 처음에는 복잡하게 시작하지 않고, HTTPS clone 후 push 시 나타나는 안내를 따라 진행해도 충분하다.

11. Node 패키지 설치

저장소를 clone하면 node_modules는 포함되어 있지 않다.

프로젝트 폴더에서 패키지를 설치한다.

cd ~/Dev/projects/chailmon-blog
npm ci

package-lock.json이 있기 때문에 새 환경에서는 npm ci를 사용하는 것이 좋다.

만약 npm ci에서 문제가 생기면 아래 명령어를 사용할 수 있다.

npm install

설치가 끝나면 node_modules 폴더가 생성된다.

12. .env 파일 복원

.env 파일은 GitHub에 올리지 않는다.

AdSense Publisher ID 같은 값은 공개 저장소에 올리면 안 되기 때문이다.

새 Mac에서는 프로젝트 루트에 .env 파일을 직접 만든다.

touch .env
code .env

안에는 아래 형식으로 값을 넣는다.

PUBLIC_ADSENSE_CLIENT=ca-pub-본인애드센스ID

중요한 점은 ads.txt에 쓰는 pub-... 값이 아니라, AdSense script에 쓰는 ca-pub-... 값이라는 것이다.

.env가 Git에 올라가지 않는지도 확인한다.

git status --ignored -s

정상이라면 아래처럼 보인다.

!! .env

!!는 Git이 해당 파일을 무시하고 있다는 뜻이다.

13. VS Code에서 프로젝트 열기

프로젝트 폴더에서 VS Code를 연다.

cd ~/Dev/projects/chailmon-blog
code .

VS Code Explorer에 아래 파일과 폴더가 보이면 프로젝트 루트를 제대로 연 것이다.

astro.config.mjs
package.json
package-lock.json
src
public
templates
wrangler.jsonc

중요한 점은 src 폴더만 여는 것이 아니라 chailmon-blog 프로젝트 전체를 열어야 한다는 것이다.

14. 로컬 개발 서버 실행

이제 로컬에서 블로그를 실행한다.

npm run dev

브라우저에서 아래 주소를 연다.

http://localhost:4321

자주 확인할 페이지는 다음과 같다.

http://localhost:4321
http://localhost:4321/blog
http://localhost:4321/categories
http://localhost:4321/blog/astro-adsense-blog-build-guide
http://localhost:4321/blog/vscode-astro-blog-workflow

개발 서버를 종료하려면 터미널에서 다음 키를 누른다.

Control + C

15. 빌드 테스트

로컬 실행이 정상이라면 실제 배포 빌드도 확인한다.

npm run build

빌드가 성공하면 dist 폴더가 생성된다.

ls dist

정상이라면 대략 아래와 같은 파일과 폴더가 보인다.

index.html
blog
categories
robots.txt
ads.txt
sitemap-index.xml

빌드 결과를 로컬에서 미리 확인하고 싶다면 다음 명령어를 사용한다.

npm run preview

브라우저에서 확인한다.

http://localhost:4321

16. 새 글 작성 테스트

새 글은 템플릿을 복사해서 만든다.

cp templates/blog-post-template.mdx src/content/blog/new-post-name.mdx

예를 들어 테스트용 초안을 만들려면 다음처럼 한다.

cp templates/blog-post-template.mdx src/content/blog/macos-astro-blog-setup-guide.mdx

MDX 파일 맨 위의 frontmatter를 수정한다.

---
title: "새 Mac에서 Astro 블로그 작업 환경 이어서 세팅하기"
description: "Mac에서 Astro 블로그 작업 환경을 다시 세팅하는 과정을 정리합니다."
pubDate: 2026-05-07
updatedDate: 2026-05-07
category: "운영하기"
tags: ["Astro", "macOS", "GitHub", "VSCode", "블로그운영"]
draft: false
cover: "/images/og-default.svg"
---

작성 중인 글이라면 draft: true, 공개할 글이라면 draft: false로 둔다.

17. Git 변경사항 확인

수정 후에는 Git 상태를 확인한다.

git status

변경 내용을 자세히 확인하려면 다음 명령어를 사용한다.

git diff

VS Code Source Control 화면에서 파일별 변경 내용도 확인할 수 있다.

커밋 전에는 아래를 꼭 확인한다.

의도한 파일만 수정됐는지
.env 파일이 포함되지 않았는지
dist 폴더가 커밋 대상에 들어가지 않았는지
draft 값이 의도한 상태인지
category 값이 정해진 세 가지 중 하나인지

현재 카테고리는 아래 세 가지로 제한되어 있다.

만들기
운영하기
써보고 남기기

18. commit과 push

빌드가 성공하고 변경사항 확인이 끝나면 커밋한다.

git add src/content/blog/macos-astro-blog-setup-guide.mdx
git commit -m "Add macOS Astro blog setup guide"
git push

여러 파일을 함께 커밋해야 한다면 git add .를 사용할 수도 있다.

git add .
git commit -m "Update blog content"
git push

다만 익숙해질 때까지는 가능한 한 커밋할 파일을 명확히 지정하는 것이 좋다.

19. Cloudflare 자동 배포 확인

GitHub에 push하면 Cloudflare가 자동으로 배포한다.

확인 위치는 다음과 같다.

Cloudflare Dashboard
→ Workers & Pages
→ chailmon-blog
→ Builds 또는 Deployments

최근 배포가 Success 상태이면 정상이다.

실제 사이트에서도 확인한다.

https://chailmon.com
https://chailmon.com/blog

새 글 주소도 확인한다.

https://chailmon.com/blog/macos-astro-blog-setup-guide

카테고리 페이지에서도 보여야 한다.

https://chailmon.com/categories/operating

최종 확인 체크리스트

새 Mac에서 Astro 블로그 작업 환경이 준비됐는지 아래 항목으로 확인할 수 있다.

Homebrew 설치 또는 확인 완료
Git 설치 완료
Git 사용자 정보 설정 완료
Node.js와 npm 설치 완료
VS Code 설치 완료
code 명령어 설정 완료
GitHub 저장소 clone 완료
npm ci 성공
.env 파일 복원 완료
npm run dev 성공
npm run build 성공
git push 성공
Cloudflare 자동 배포 성공

이 체크리스트를 통과하면 새 Mac에서도 기존 블로그 작업을 안정적으로 이어갈 수 있다.

마무리

새 Mac에서 Astro 블로그 작업 환경을 이어서 세팅할 때 핵심은 복잡하지 않다.

필요한 것은 Git, Node.js, VS Code, GitHub 인증, 그리고 .env 복원이다.

특히 .env 파일은 GitHub에 올라가지 않기 때문에 새 컴퓨터에서 반드시 직접 다시 만들어야 한다.

또 로컬에서 npm run dev만 확인하고 끝내지 말고, npm run build, git push, Cloudflare 자동 배포까지 확인해야 실제 운영 흐름이 완성된다.

이 과정을 한 번 정리해두면 나중에 컴퓨터를 바꾸더라도 블로그 작업 환경을 훨씬 빠르게 복구할 수 있다.