해외몰 초기 개발환경 세팅 가이드

해외몰 개발환경 세팅 가이드

해외몰 개발을 위한 초기 개발환경을 설정하는 방법을 단계별로 안내합니다.
Shopify, Node.js, Homebrew 등 필수 도구들의 설치 및 설정 방법을 포함합니다.

💡 이 가이드는 Shopify 기반 해외몰 개발을 위한 환경 설정에 중점을 둡니다.

플랫폼별 설치 요구사항

요구사항	macOS	Windows
운영체제	macOS 10.15+	Windows 10/11
관리자 권한	필요	필요 (PowerShell)
터미널	기본 터미널	PowerShell (관리자)

1. 패키지 관리자 설치

설명: 운영체제별로 필수 도구를 쉽게 설치·관리할 수 있는 패키지 관리자를 설치합니다.

macOS (Homebrew)

Windows (Chocolatey)

Homebrew 설치 (macOS 전용)

설명: macOS에서 필수 도구를 쉽게 설치·관리할 수 있는 패키지 관리자입니다.

# Homebrew 설치 (macOS 전용)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

터미널에서 실행: 위 명령어를 터미널에 붙여넣고 Enter를 누르세요.

Chocolatey 설치 (Windows 전용)

설명: Windows에서 다양한 개발 도구를 쉽게 설치할 수 있는 패키지 관리자입니다.

# Chocolatey 패키지 관리자 설치 (Windows 전용)
Set-ExecutionPolicy Bypass -Scope Process -Force; [System.Net.ServicePointManager]::SecurityProtocol = [System.Net.ServicePointManager]::SecurityProtocol -bor 3072; iex ((New-Object System.Net.WebClient).DownloadString('https://community.chocolatey.org/install.ps1'))

PowerShell에서 실행: PowerShell을 관리자 권한으로 실행한 후 위 명령어를 입력하세요.

설치 확인

# Chocolatey 버전 확인
choco --version

⚠️ 'choco' 명령어 인식 안 될 때 해결방법

오류 메시지: "'choco'은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다"

원인: Windows 환경변수에 Chocolatey 경로가 등록되지 않아 발생하는 문제입니다.

해결 방법:

Chocolatey 설치 경로 확인: C:\ProgramData\chocolatey\bin
Windows 설정 → 시스템 환경 변수 편집
환경변수 → 시스템 변수 → Path 선택
새로 만들기 → C:\ProgramData\chocolatey\bin 추가
확인 후 터미널 재시작

🔗 참고 링크: Chocolatey 환경변수 설정 가이드

2. Node.js

1

설치 방법 (맥/윈도우 공통)

설명: Node.js는 자바스크립트 런타임 환경으로, 다양한 개발 도구들과 연결됩니다.

Node.js 공식 사이트에서 LTS 버전 다운로드 후 설치해주세요.

2

설치 확인

설치 후, 아래 명령어로 정상 설치 확인할 수 있습니다. (맥의 경우 터미널, 윈도우의 경우 명령 프롬프트 또는 PowerShell)

# Node.js 버전 확인
node -v

# npm 버전 확인
npm -v

✅ Node.js 설치 확인 체크리스트

Node.js가 정상적으로 설치되었는지 확인

npm이 함께 설치되었는지 확인

버전 정보가 정상적으로 출력되는지 확인

LTS 버전 (18.x 이상)인지 확인

3. Shopify 개발 환경 설정

Shopify 테마 개발을 위한 환경을 설정합니다.

1

Shopify CLI 설치

설명: 테마 개발, 미리보기, 배포 등 다양한 작업을 CLI로 실행 가능

설치 명령어

# Shopify CLI 설치
npm install -g @shopify/cli@latest

공식 문서 보기

⚠️ Windows에서 npm 설치 오류 발생 시

오류 메시지: "이 시스템에서 스크립트를 실행할 수 없으므로 C:\Program Files\nodejs\npm.ps1 파일을 로드할 수 없습니다."

원인: PowerShell의 실행 정책(Execution Policy) 때문에 발생하는 문제입니다.

해결 방법:

PowerShell을 관리자 권한으로 실행 (시작 메뉴에서 PowerShell 검색 → 우클릭 → 관리자 권한으로 실행)
실행 정책 변경: 아래 명령어 입력 후 Y 입력

# PowerShell 실행 정책 변경
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

💡 참고: RemoteSigned는 로컬 스크립트는 실행 가능하고, 인터넷에서 다운로드한 스크립트는 서명이 필요하여 보안성과 편의성의 균형을 잡은 옵션입니다.

2

Shopify Theme Kit 설치

설명: Shopify 테마 개발을 위한 Theme Kit 설치 방법을 안내합니다.

macOS/Linux

Windows

macOS/Linux 설치

# macOS/Linux에서 Theme Kit 설치
curl -s https://shopify.github.io/themekit/scripts/install.py | python3

터미널에서 위 명령어를 실행하세요.

Windows 설치

# Windows에서 Theme Kit 설치 (Chocolatey 사용)
choco install themekit

PowerShell을 관리자 권한으로 실행한 후 위 명령어를 입력하세요.

⚠️ 'theme' 명령어 인식 오류 해결 방법

오류 메시지: "'theme' 용어가 cmdlet, 함수, 스크립트 파일 또는 실행할 수 있는 프로그램 이름으로 인식되지 않습니다"

원인: Theme Kit 또는 Shopify CLI가 설치되어 있지만, 해당 실행 파일의 경로가 Windows 환경변수(Path)에 등록되지 않아, 커맨드라인(cmd, PowerShell 등)에서 'theme' 명령어를 인식하지 못하는 문제입니다.

✅ 해결 방법 (Shopify CLI 기준):

theme 명령어는 Shopify CLI에서 사용되므로, 아래는 Shopify CLI 경로 등록 방법입니다.

1. Shopify CLI 설치 경로 확인

기본 경로는 보통:

# Shopify CLI 기본 설치 경로
C:\Users\[사용자명]\AppData\Local\shopify\bin

여기 안에 shopify.exe가 있어야 합니다.

2. 환경 변수 설정

작업 경로: 제어판 > 시스템 > 고급 시스템 설정 > 환경 변수

사용자 변수에서 Path 항목 선택 → 편집 클릭
새로 만들기 클릭 후 다음 경로 추가:

# 환경 변수에 추가할 경로
C:\Users\[사용자명]\AppData\Local\shopify\bin

확인 후 모든 창 닫고, 터미널 재시작

💡 팁: 환경변수 설정 후에는 반드시 터미널을 완전히 종료하고 다시 실행해야 변경사항이 적용됩니다.

설치 확인

# Theme Kit 버전 확인
theme version

버전 정보가 표시되면 설치가 완료된 것입니다.

자주 사용하는 CLI 명령어

# 로컬 변경사항을 스토어에 실시간 반영 (테마 미리보기 가능)
theme watch

# 라이브 테마에 변경사항 실시간 반영 (주의 요망)
theme watch --allow-live

⚠️ --allow-live 옵션 사용 시 주의사항

라이브 테마에 직접 영향을 줄 수 있습니다
실수로 고객이 보는 페이지가 변경될 수 있습니다
사용 전 반드시 백업을 확인하세요
테스트 완료 후에는 즉시 중단하세요

3

Theme Access 앱 설치

용도: Shopify CLI와 연동할 수 있는 API 비밀번호를 발급받기 위해 사용

설치 방법

Shopify 앱스토어에서 Theme Access 검색 및 설치
이메일로 비밀번호 수신
해당 비밀번호를 config.yml에 설정

4

config.yml 설정 예시

development:
  password: [your-password]         # Theme Access 앱에서 발급받은 비밀번호
  theme_id: [your-theme-id]         # 작업할 테마의 ID
  store: [your-store.myshopify.com] # 스토어 도메인
  ignore_files:                     # 업로드 제외 파일
    - config/settings_data.json
    - sections/*.json
    - locales/*
    - templates/*.json

⚠️ 주의: theme_id는 실수로 라이브 테마를 설정하지 않도록 주의하세요.

5

내부용 해외 계정정보

설명: 해외몰 개발에 필요한 계정 정보들을 정리한 내부 문서입니다.

내부용 해외 계정정보 시트

💡 참고: 이 시트에는 Shopify 스토어 계정 정보들이 포함되어 있습니다.

6

개발 참고 문서

Liquid 문서 – 테마에서 사용되는 템플릿 언어
Shopify 테마 개발 가이드 – 테마 구조 및 커스터마이징 설명
Liquid 객체 목록 – 사용 가능한 데이터 객체

7

테스트 완료 페이지 공유 방법

설명: 개발 중인 테마를 미리보기하고 공유할 때 사용하는 방법입니다.

Preview Theme ID 사용법

테스트 완료 페이지를 공유할 때 URL 뒤에 preview_theme_id 파라미터를 추가하면 됩니다.

# 테스트 완료 페이지 공유 URL 예시
https://foodology-global.com?preview_theme_id=146034786471

8

Shopify Liquid 확장 프로그램 설치 권장

설명: VS Code에서 Shopify Liquid 템플릿 언어의 문법 하이라이팅과 자동완성을 지원하는 확장 프로그램입니다.

주요 기능

Liquid 문법 하이라이팅 및 자동완성
Shopify Liquid 객체 및 필터 지원
코드 스니펫 제공
문법 오류 검사

Shopify Liquid 확장 프로그램 다운로드

💡 팁: 이 확장 프로그램을 설치하면 Liquid 템플릿 작성 시 훨씬 편리하게 개발할 수 있습니다.

5. 환경 설정 완료

기본 개발환경 설정이 완료되었습니다. 이제 Shopify 테마 개발을 시작할 수 있습니다.

전체 설치 확인 체크리스트

1. 패키지 관리자

Homebrew (macOS) 또는 Chocolatey (Windows) 설치 완료

패키지 관리자 명령어가 터미널에서 정상 작동

2. Node.js

Node.js LTS 버전 설치 완료

npm이 함께 설치되어 정상 작동

버전 확인 명령어 실행 성공

3. Shopify CLI

Shopify CLI 전역 설치 완료

Theme Kit 설치 완료

Shopify 계정 연결 및 인증 완료

4. 개발 환경

config.yml 파일 설정 완료

Theme Access 앱 설치 및 비밀번호 발급

VS Code Shopify Liquid 확장 프로그램 설치

🎉 모든 항목을 체크했다면 개발 환경 설정이 완료되었습니다!

💡 개발 팁

개발 중에는 항상 theme watch 명령어를 사용하여 실시간으로 변경사항을 확인하세요.
라이브 테마에 영향을 주지 않도록 주의하세요!
변경사항을 테스트할 때는 개발용 테마를 사용하는 것이 안전합니다.
정기적으로 백업을 확인하고 중요한 변경사항은 버전 관리하세요.

해외몰 개발환경 세팅 가이드

플랫폼별 설치 요구사항

1. 패키지 관리자 설치

Homebrew 설치 (macOS 전용)

Chocolatey 설치 (Windows 전용)

설치 확인

⚠️ 'choco' 명령어 인식 안 될 때 해결방법

해결 방법:

2. Node.js

설치 방법 (맥/윈도우 공통)

설치 확인

✅ Node.js 설치 확인 체크리스트

3. Shopify 개발 환경 설정

Shopify CLI 설치

설치 명령어

⚠️ Windows에서 npm 설치 오류 발생 시

해결 방법:

Shopify Theme Kit 설치

macOS/Linux 설치

Windows 설치

⚠️ 'theme' 명령어 인식 오류 해결 방법

✅ 해결 방법 (Shopify CLI 기준):

1. Shopify CLI 설치 경로 확인

2. 환경 변수 설정

설치 확인

자주 사용하는 CLI 명령어

⚠️ --allow-live 옵션 사용 시 주의사항

Theme Access 앱 설치

설치 방법

config.yml 설정 예시

내부용 해외 계정정보

개발 참고 문서

테스트 완료 페이지 공유 방법

Preview Theme ID 사용법

Shopify Liquid 확장 프로그램 설치 권장

주요 기능

5. 환경 설정 완료

전체 설치 확인 체크리스트

1. 패키지 관리자

2. Node.js

3. Shopify CLI

4. 개발 환경

💡 개발 팁

비메오 코드 생성기

비메오 다이렉트 링크 가져오는 방법