Mac에서 Ghost 테마 수정을 위한 nvm, node.js, ghost 개발 환경 구축하기

nvm으로 Node.js 설치부터 로컬 Ghost 실행까지

Ghost를 설치했으니, 다음 단계는 나만의 블로그 스타일을 만드는 일이다. Ghost는 테마를 자유롭게 수정하거나 새로 만들 수 있도록 잘 설계되어 있으며, 이를 위해선 로컬 개발 환경을 준비해야 한다.

특히 Mac을 사용하는 경우, 시스템의 Node.js 버전이나 패키지 구성에 따라 오류가 발생할 수 있기 때문에 버전 관리가 핵심이다. 이 글에서는 Ghost에서 공식 권장하는 Node.js 버전을 nvm으로 설치하고, ghost-cli를 활용해 로컬에서 Ghost를 실행해 테마를 개발하는 과정을 단계별로 안내한다.

1. Ghost 테마 개발 환경의 구조 이해

Ghost는 Node.js 기반의 Headless CMS다. 기본적으로 content/themes 디렉토리에 테마가 위치하며, HTML을 확장한 Handlebars 템플릿 언어로 작성되어 있다. (나에겐 HTML 템플릿 언어 중에 제일 직관적이고 이해하기 쉬웠다.)

테마를 수정하거나 개발하려면 Ghost 인스턴스를 로컬에서 실행해 두고, 테마 파일을 바로 수정하며 변경사항을 브라우저에서 확인하는 흐름이 가장 효율적이다.

2. Ghost 공식 권장 Node.js 버전 확인

Ghost는 모든 버전에서 최신 Node.js를 지원하지는 않는다. 공식 문서에서 아래와 같은 명시가 있다:

Ghost 5.x 는 20.x (Node v20 Iron LTS) 버전을 지원합니다.
https://ghost.org/docs/faq/node-versions/

✅ 권장 버전: 20.x (Node v20 Iron LTS)
Ghost는 안정성과 호환성 측면에서 LTS(Long-Term Support) 버전만을 지원 대상으로 삼는다. 이 때문에 nvm과 같은 버전 관리 도구가 필요하다.

3. nvm(Node Version Manager) 설치하기

macOS에서 Node.js 버전을 안전하게 관리하려면 nvm이 가장 좋은 선택이다.

⬇ 설치 방법

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

설치가 끝난 후, 다음 명령어를 입력해 .zshrc 파일을 생성한 후

sudo nano .zshrc

아래의 내용을 붙혀넣기해 준다.

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

4. Node.js 20.xx 설치 및 사용 설정

# Node.js 다운로드 및 설치:
nvm install 20

# Node.js 버전 확인:
node -v # "v20.19.4"가 출력되어야 합니다.
nvm current # "v20.19.4"가 출력되어야 합니다.

npm 버전 확인:
npm -v # 10.8.2가 출력되어야 합니다.

5. Ghost CLI 설치하기

Ghost는 CLI 도구를 통해 로컬 설치, 실행, 디버깅 등을 간편하게 할 수 있다.

npm install ghost-cli@latest -g

6. 로컬 Ghost 개발 환경 구축

이제 Ghost를 로컬에서 설치하고 실행할 수 있다.

📁 디렉토리 생성

mkdir ~/ghost-dev
cd ~/ghost-dev

👻 Ghost 설치

ghost install local

위 명령어는 Ghost를 SQLite DB로 로컬 설치하며, 실행까지 자동으로 수행된다.

7. 로컬 서버 확인 및 관리자 페이지 접속

설치가 완료되면 기본적으로 다음 주소에서 Ghost가 실행된다:

• 블로그 주소: http://localhost:2368
• 관리자 페이지: http://localhost:2368/ghost

브라우저에서 접속해 사용자 설정을 진행하면 된다.

8. 테마 폴더 구조와 수정 방법

Ghost의 테마는 content/themes 디렉토리에 위치한다. 설치된 테마(Casper 등)를 직접 복사해서 새 테마로 사용하거나, Ghost 마켓플레이스에서 원하는 테마를 다운로드해 적용할 수 있다.

✍ 기본적인 테마 커스터마이징 흐름

cd content/themes
cp -R casper mytheme
cd mytheme

package.json, default.hbs, index.hbs, partials/ 등을 수정하면서 바로바로 로컬 서버에서 반영 결과를 확인할 수 있다.

마무리: 이제부터는 테마를 변경할 수 있는 기본 환경이 구성되었다.

Ghost는 심플하면서도 강력한 커스터마이징 기능을 제공한다. 위 과정을 통해 Mac 환경에서 테마 개발을 시작할 수 있으며, 필요에 따라 Git으로 테마를 버전 관리하거나 배포 자동화도 가능하다.

무엇보다 Ghost CLI와 nvm을 활용한 이 구조는 안정적인 버전 호환성과 빠른 수정 반영을 동시에 충족시켜준다.