워드프레스 개발환경 무작정 따라하기: wp-env

워드프레스 개발환경 무작정 따라하기: wp-env 활용 가이드

워드프레스 플러그인/테마 개발을 위한 로컬 개발환경 구축은 복잡해 보일 수 있지만, wp-env를 사용하면 매우 간단하게 시작할 수 있습니다. 아래는 완전 초보자를 위한 단계별 따라하기입니다.

wp-env는 플러그인과 테마를 구축하고 테스트하기 위한 로컬 WordPress 환경을 쉽게 설정할 수 있게 해줍니다. 설치가 간단하고 구성이 필요하지 않습니다.

@wordpress/env – Block Editor Handbook | Developer.WordPress.org

1. 필수 구성 요소

wp-env는 일반적으로 사용되는 몇 가지 개발자 도구에 의존합니다:

• Docker: wp-env는 Docker로 구동됩니다. Windows에서 Docker를 설치하는 데 사용할 수 있는 지침이 있습니다(WSL2 백엔드를 권장합니다), macOS 및 Linux에서 사용할 수 있습니다.
  • Docker Desktop – Windows에서 다운로드 및 설치 | Microsoft Store – Microsoft Apps
  • dev home에서 응용프로그램 설치 해도 되는데, 스토어가 버전관리 용이
• Node.js: wp-env는 노드 스크립트로 작성되었습니다. 최신 LTS 버전을 설치하려면 nvm 같은 버전 관리 도구 사용 권장.
  • npm (Node.js 설치하면 같이 설치됨)
• Git: Git은 워드프레스, 플러그인, 테마와 같은 소스 컨트롤에서 소프트웨어를 다운로드하는 데 사용됩니다.
• (옵션) VS Code 같은 코드 에디터
• Git, GitHub Desktop, Node.js 전부 dev home에서 설치하면 편리함.

2. 설치

1️⃣ 전역 패키지로 설치 (권장 사항)

필수 구성 요소가 설치된 것을 확인한 후, 다음과 같이 wp-env를 글로벌로 설치할 수 있습니다:

터미널(명령 프롬프트)에서 아래 명령어로 wp-env를 전역 설치합니다.

npm -g i @wordpress/env

설명

• -g: 전역(global) 설치 옵션
• i: install (줄임말)
• @wordpress/env: 워드프레스 dev용 Docker 환경 툴

전역 설치하면 어디서든 wp-env 명령어 쓸 수 있어.
→ 이건 개별 프로젝트 npm install 말고 전역 설치니까 명확하게 구분해두자.

이러면 어떤 디렉토리에서도

wp-env start

바로 가능.

혹시 wp-env 명령어 전역으로 설치했는지 확인해보려면

wp-env --version

치면 버전 나옴.
이러면 정상 설치된 거야.

설치된 전역 패키지 목록 확인

npm -g list –depth=0 해서
전역 패키지 뭐 설치돼 있는지도 확인 가능해.
만약 워드프레스 dev 패키지 충돌이나 버전 꼬임 있을 때 유용해.

전역 설치 경로 확인

npm root -g

2️⃣로컬 패키지로 설치

프로젝트에 이미 package.json 있는 경우 로컬 패키지로 wp-env를 사용할 수도 있습니다. 먼저 개발(dev) 종속성으로 wp-env를 로컬에 설치하세요:

npm i @wordpress/env --save-dev

wp-env를 전역적으로 설치한 경우에도 이를 실행하면 로컬, 프로젝트 수준의 패키지가 자동으로 실행됩니다. 또는 npm.npx와 함께 자동으로 설치되는 유틸리티가 노드 모듈을 통해 설치된 wp-env와 같은 바이너리를 찾아서 실행하는 npx를 통해 wp-env를 실행할 수도 있습니다. 예를 들어, npx wp-env start --update

---

@wordpress/env

3. 사용법

환경 시작하기

먼저 Docker가 실행 중인지 확인합니다. 시스템 트레이 또는 메뉴 표시줄에서 Docker 아이콘을 클릭하여 이 작업을 수행할 수 있습니다.

그런 다음 WordPress 플러그인 또는 테마가 포함된 디렉토리로 변경합니다.

개발할 플러그인/테마 폴더로 이동

예시: 깃허브 Gutenberg 저장소(리포지토리)

• Git Workflow – Block Editor Handbook | Developer.WordPress.org
• 코드 컨트리뷰션 시작하기 – 블록 편집기 핸드북 | Developer.WordPress.org
• gutenberg/packages/env at trunk · WordPress/gutenberg
• gutenberg/CONTRIBUTING.md at trunk · WordPress/gutenberg
• Docs / Introduction – page ⋅ Storybook

GitHub Desktop – Current repository – Add – Clone repository – Your repositories – Local Path (onedrive에 문서 폴더 동기화 되어 있을 경우 새 경로 설정)
This repository if a folk. How do you plan to use it? – To contribute to the parent project (Pull request, Issues등 때문에 헷갈릴 수 있는데, 이거 아님)
For my own purposes (git workflow에서 브랜치가 your folk에 based on 해야해서 이거로 해야함)

• WordPress/gutenberg
• Jiwoon-Kim/gutenberg

bashcd ~/path/to/a/wordpress/plugin$ cd ~/gutenberg

cd C:\Users\thaum\dev
git clone https://github.com/Jiwoon-Kim/gutenberg.git 
cd C:\Users\thaum\dev\gutenberg
git switch -c update/my-branch
git remote add upstream https://github.com/WordPress/gutenberg.git

워드프레스 개발환경 시작

아래 명령어로 로컬 워드프레스 환경을 실행합니다.

$ wp-env start

마지막으로 웹 브라우저에서 http://localhost:8888 로 이동하여 WordPress가 로컬 WordPress 플러그인 또는 테마가 실행 및 활성화된 상태로 실행되는 것을 확인하세요.
기본 로그인 자격 증명은 username: admin password: password 입니다.

• 브라우저에서 http://localhost:8888 접속
• 기본 로그인:
  • 아이디: admin
  • 비밀번호: password

---

자주 사용하는 명령어

명령어	설명
wp-env start	개발환경 시작
wp-env stop	개발환경 중지
wp-env clean all	데이터베이스 초기화(모든 데이터 삭제)
wp-env destroy	모든 환경 완전 삭제 완전 초기화(모든 컨테이너, 볼륨 삭제)
wp-env run cli wp plugin install 플러그인명	플러그인 설치
wp-env run cli bash	CLI 컨테이너에서 bash 쉘 실행

요약

• Docker, Node.js, Git 설치
• npm -g i @wordpress/env로 wp-env 설치
• 플러그인/테마 폴더에서 wp-env start 실행
• 브라우저에서 http://localhost:8888로 접속해 개발 시작

wp-env를 활용하면 복잡한 환경설정 없이 워드프레스 개발을 바로 시작할 수 있습니다.

Citations:

1. 시작하기 – 블록 편집기 핸드북 | Developer.WordPress.org
2. chore: 보안 취약점 해결을 위한 npm audit fix 실행 by 김지운 · 풀 리퀘스트 #70016 · 워드프레스/구텐베르크
3. 코드로 기여 – WordPress 코어 만들기
4. 기계 설정 – Make WordPress.org
5. WordPress/meta-environment: 공식 WordPress.org 웹사이트를 Varying Vagrant 설치 파일로 프로비저닝하는 스크립트 모음입니다.
6. global.wordpress.org – WordPress.org 만들기
7. WordPress.org – WordPress.org 만들기

---

wp-env 개념 정리

• wp-env는 Docker 기반의 로컬 워드프레스 개발 툴.
• 기본적으로 Docker 컨테이너 안에 워드프레스 환경을 자동으로 띄워줘.
• wp-env start 하면 Docker가 컨테이너 생성 & 실행.
• 이때 Docker 컨테이너 목록 보려면:

docker ps

하면 현재 실행 중인 컨테이너 목록이 테이블 형식으로 쭈욱 보여.

📌 **전역 설치(Global installation)**의 정확한 의미

명령어에서 말하는 **전역(global)**이란,

• 특정 디렉토리 내부에서만 쓰이는 게 아니라,
• 컴퓨터 전체의 환경 어디서든 쓸 수 있도록 설치하는 걸 뜻해.

예를 들면,

• npm install -g 패키지 → Node.js의 패키지를 모든 프로젝트 어디서든 명령어로 사용 가능하게 설치
• composer global require → PHP의 composer로 컴퓨터 전체 scope에서 쓰이는 composer package 설치
• wp-env 같은 경우도 마찬가지. npm install -g @wordpress/env로 전역 설치하면 어떤 프로젝트 디렉토리에서든 wp-env 명령어를 호출 가능

📌 그런데, 이 **전역(global)**의 실제 경로는?

그렇다고 이게 시스템 전체 /usr/bin이나 C:\Windows\System32 같은 OS 핵심 디렉토리에 박히는 건 아님.

• Node.js 예)
  윈도우라면 C:\Users\{사용자}\AppData\Roaming\npm
  맥/리눅스라면 ~/.npm-global 또는 /usr/local/bin
• Composer 예)
  윈도우: C:\Users\{사용자}\AppData\Roaming\Composer\vendor\bin
  맥/리눅스: ~/.composer/vendor/bin

이 경로가 OS PATH에 등록돼 있어서 명령어를 어디서든 호출할 수 있는 것.

📌 wp-env start를 실행한 지금 상황은?

지금은 C:\Users\thaum\dev\gutenberg 디렉토리 안에서 wp-env start를 실행했으니까,

• 해당 디렉토리 안에 있는 .wp-env.json 파일을 기준으로
• 도커 컨테이너를 띄우는 것

전역 설치 여부와는 별개로,

• wp-env 명령어가 전역으로 설치돼 있어야 해당 명령어를 어디서든 쓸 수 있고,
• 프로젝트 단위로 실행할 땐 **해당 디렉토리의 설정파일(.wp-env.json)**을 읽는 거지.

---

📌 Git & GitHub 개념 정리

이거 Git & GitHub 용어들 헷갈리기 딱 좋은 거라 정리해볼게. 지금 워드프레스 코어 기여하려면 꼭 알고 넘어가야 하는 개념이기도 하고.

용어	설명
fork	다른 사람(혹은 공식) 저장소를 내 깃허브 계정으로 복사해오는 것. 원본은 그대로 있고, 내 계정에 복사본이 생김. 기여하려면 보통 fork해서 작업함.
repository (repo)	깃허브에서 하나의 코드 프로젝트를 담고 있는 공간. 워드프레스 gutenberg도 하나의 repository.
trunk	워드프레스에서는 보통 main 브랜치 대신 trunk라는 이름의 메인 브랜치를 씀. 최신 개발 내용이 모이는 메인 가지.
branch	원래 코드를 건드리지 않고, 새로운 기능이나 수정을 작업할 수 있는 가지(branch). 보통 feature/my-feature 같은 이름으로 만듦.
pull origin	origin은 내 깃허브 repo를 의미. git pull origin trunk 하면 내 깃허브의 trunk에서 최신 코드를 가져옴.
upstream	보통 원본 repo를 upstream으로 지정함. 예) 워드프레스 공식 gutenberg repo. git remote add upstream https://github.com/WordPress/gutenberg.git 이렇게 연결 가능.
fetch origin / fetch upstream	원격 저장소(origin 또는 upstream)의 최신 이력을 가져오기만 함. 아직 병합은 안 됨.
sync fork	내 포크된 저장소를 원본(official repo)과 동기화하는 것. 워드프레스 코어 같은 경우 upstream에서 최신 커밋을 가져와서 내 포크에 반영하는 거.
pull request (PR)	내가 작업한 브랜치의 변경사항을 원본 repo(혹은 메인 브랜치)에 반영해달라고 요청하는 것. 워드프레스 기여는 이걸 통해 이뤄짐.

---

📖 예제 시나리오

1. 워드프레스 gutenberg repo를 fork → 내 계정에 복사본 생김
2. 내 로컬에 내 fork repo를 clone
3. upstream remote 등록 → 원본 공식 repo 연결
4. 최신 trunk로 내 fork를 sync
5. 내 fork에서 작업용 branch 생성
6. 작업 후 커밋, 푸시
7. 내 fork → WordPress/gutenberg trunk로 PR 보냄

---

📌 명령어 요약

# upstream 등록 (한번만)
git remote add upstream https://github.com/WordPress/gutenberg.git

# 원본 최신 trunk 가져오기
git fetch upstream
git checkout trunk
git merge upstream/trunk

# 내 fork에 반영
git push origin trunk

# 새 브랜치 생성
git checkout -b update/my-feature

# 작업하고 커밋 푸시
git add .
git commit -m "update: added feature"
git push origin update/my-feature

# 깃허브에서 PR 보내기

---

GitHub에서는 Pull Request(PR) 가 사실상 두 브랜치 간의 비교(diff)와 merge 제안을 의미해.
그리고 PR은 아래 요소로 구성돼:

---

📌 Pull Request 구조

요소	설명
베이스 브랜치 (base branch)	PR로 머지하려는 대상 브랜치 (보통 trunk, main 등)
헤드 브랜치 (head branch)	변경사항을 담은 작업 브랜치 (포크의 my-feature-branch 같은 거)
커밋 히스토리	PR 열 당시 헤드 브랜치에 있는 커밋 목록
상호 연결 상태	PR은 헤드 브랜치가 업데이트되면 자동으로 PR 화면에도 반영됨

즉, PR은 브랜치에 귀속돼 있어.

---

📌 중요한 특징

• PR 올리고 나서 헤드 브랜치에서 커밋을 추가하거나 수정하면 → PR 화면에도 실시간으로 반영됨.
• 만약 헤드 브랜치를 삭제하면 → 해당 PR은 Closed 처리되고 더 이상 사용할 수 없음.
• 같은 이름으로 브랜치를 다시 만들어도 → 그 PR과는 연결 안 됨. 새 PR을 만들어야 해.

---

📌 예시

베이스: WordPress/gutenberg trunk
헤드: Jiwoon-Kim/gutenberg update/my-branch

이 상태에서 PR 만들었으면
→ update/my-branch 브랜치에 커밋 추가하면 PR에 실시간으로 반영
→ update/my-branch 삭제하면 PR도 Closed
→ 같은 이름으로 브랜치 다시 만들어도 기존 PR과 무관

---

📌 정리

상황	PR 영향
브랜치 커밋 추가	PR에 실시간 반영
브랜치 삭제	PR 자동 Close
같은 이름 브랜치 새로 만듦	PR과 무관. 새 PR 필요

---

저 LF → CRLF 경고는 윈도우 개발환경에서 자주 뜨는 거라서 설명 잠깐 해줄게.

---

📌 왜 뜨는 거냐?

• LF (Line Feed) : 유닉스/리눅스/macOS에서 사용하는 줄바꿈
• CRLF (Carriage Return + Line Feed) : 윈도우에서 사용하는 줄바꿈

지금 네 깃 설정이
core.autocrlf=true
로 되어 있어서, 체크아웃할 때 LF → CRLF 바꾸고, 커밋할 땐 다시 CRLF → LF로 돌리는 설정인데
현재 워킹카피에서 LF였던 파일이 CRLF로 바뀌는 걸 감지해서 저 경고를 띄워준 거야.

참고: 설정 확인하려면

git config --get core.autocrlf

📌 해결법

만약 네 개발환경 줄바꿈 강제를 LF로 통일하고 싶으면
전역 설정 변경 가능:

git config --global core.autocrlf input

• true : 체크아웃할 때 LF→CRLF, 커밋할 때 다시 CRLF→LF
• input : 체크아웃할 땐 냅두고, 커밋할 때 CRLF→LF
• false : 아무것도 안 건드림

대부분 OSS 개발자들은 input 씀
네가 OSS PR 많이 할 거면 input 추천.

---

wporg-main-2022 설치 방법

• WordPress/wporg-main-2022: A block-based child theme for WordPress.org, plus local environment
• Jiwoon-Kim/wporg-main-2022: A block-based child theme for WordPress.org, plus local environment

이건 워드프레스.org 공식 사이트 테마 개발용 레포지토리
👉 https://wordpress.org 사이트에 쓰이는 그 테마.

구조가 조금 달라. 근데 원리와 세팅법은 비슷해서 같이 비교해볼 수 있어.

Development

필수 구성 요소

• Docker
• Node/npm
• Yarn
  • Yarn 설치 및 사용 방법
  • npm install -g yarn
• Composer
  • Composer
• SVN
  • Downloads · TortoiseSVN

Yarn

• npm의 대체 패키지 매니저
• npm install 대신 yarn install
• 같은 package.json 파일을 기반으로 JS 라이브러리, 개발 툴 설치/관리
• 차이점 :
  • 캐시 빠름
  • yarn.lock으로 정확한 버전 고정
  • 워드프레스 Gutenberg 프로젝트에도 npm 대신 yarn 쓰는 플러그인/테마 꽤 있음

Composer

• PHP용 의존성 관리 도구
• package.json이 JS용이면, composer.json은 PHP용
• 플러그인이나 테마에서 PHP 라이브러리(예: Monolog, Guzzle) 설치할 때 사용

PHP는 Composer와 같은 PHP 기반 도구를 실행하는 데 필요한 언어이기 때문에, Composer를 설치하기 전에 PHP가 시스템에 올바르게 설치되어 있어야 해. PHP는 주로 웹 서버나 CLI 환경에서 사용되며, 설치 위치는 운영체제에 따라 다를 수 있어. 아래는 각 운영체제에 맞는 PHP 설치 방법과 경로 설정에 대한 안내야.

1. Windows에서 PHP 설치 방법

(1) PHP 다운로드

1. PHP 공식 웹사이트로 가서 Non Thread Safe (NTS) 버전을 다운로드해. (보통 x64버전으로 다운로드하면 돼.)
2. 다운로드한 ZIP 파일을 적당한 폴더에 압축을 풀어.

추천 경로

• PHP 설치
  • 윈도우라면 https://windows.php.net/download/ 에서 최신 PHP zip 다운받아서 C:\php 같은 경로에 풀고, PATH에 등록.
• Composer 설치
  • https://getcomposer.org/download/ 가서 Windows installer 받으면 쉽게 설치 가능.

SVN (Subversion)

• 깃 이전 세대의 버전 관리 시스템
• 워드프레스 공식 플러그인 디렉토리 배포할 때 필수
  (지금도 워드프레스.org 플러그인 등록하면 SVN 저장소 배정해줌)

Subversion (SVN) 설치: SVN을 시스템에 설치하면 이 문제를 해결할 수 있습니다.

• Windows에서는 TortoiseSVN을 다운로드하여 설치할 수 있습니다.
• 설치할 때 PATH에 SVN을 추가하는 옵션을 선택하세요.

TortoiseSVN을 설치하면서 PATH에 SVN을 추가하는 방법을 아래에 설명드립니다.

1. TortoiseSVN 다운로드 및 설치

• TortoiseSVN 공식 웹사이트에서 Windows 버전의 설치 파일을 다운로드합니다.
• TortoiseSVN download | SourceForge.net
• 다운로드한 설치 파일을 실행하여 설치를 시작합니다.

2. TortoiseSVN 설치 과정

설치 중에 PATH에 SVN을 추가하는 옵션을 선택해야 합니다.

1. 설치 시작:
   • 다운로드한 설치 파일을 실행합니다. 설치 마법사가 시작됩니다.
2. 설치 옵션 선택:
   • “Next” 버튼을 클릭하여 설치 단계로 진행합니다.
3. ‘Optional Components’ 설정:
   • 설치 옵션 화면에서 Optional Components 항목을 볼 수 있습니다. 여기에서 “Command Line Client Tools” 옵션을 선택하세요.이 옵션을 선택하면 TortoiseSVN의 명령줄 도구(svn)가 PATH에 자동으로 추가됩니다.
   중요: “Command Line Client Tools”를 선택하지 않으면 svn 명령어를 사용할 수 없습니다. 반드시 이 항목을 선택해야 합니다.
4. 설치 완료:
   • 나머지 설정을 완료하고 설치를 진행합니다.
   • 설치가 완료되면, 시스템에 svn 명령어가 PATH에 추가되어 명령줄에서 사용할 수 있습니다.

3. 설치 후 svn 명령어 확인

TortoiseSVN을 설치한 후 svn 명령어가 제대로 작동하는지 확인하려면 명령 프롬프트(cmd)나 PowerShell을 열고 다음 명령어를 입력해 보세요:

svn --version

정상적으로 설치되었다면 SVN 버전 정보가 출력될 것입니다.

4. TortoiseSVN 사용

• 이제 svn 명령어를 명령줄에서 사용할 수 있으므로, Composer에서 요구하는 SVN을 사용할 수 있습니다.
• 또한 TortoiseSVN은 Windows에서 파일 탐색기와 통합되어 SVN 리포지토리를 관리하는 GUI 도구로도 사용할 수 있습니다.

이 방법으로 TortoiseSVN을 설치하고, svn 명령어를 PATH에 추가하여 문제를 해결할 수 있습니다.

---

Setup

repo 종속성을 설정합니다.

yarn
composer install
yarn setup:tools

로컬 환경을 시작합니다.

yarn wp-env start

설치 스크립트를 실행합니다.

yarn setup:wp

테마를 구축합니다.

yarn workspaces run build

---

C:\Users\thaum\dev\wporg-main-2022>yarn setup:tools yarn run v1.22.22 $ TEXTDOMAIN=wporg composer exec update-configs ‘TEXTDOMAIN’은(는) 내부 또는 외부 명령, 실행할 수 있는 프로그램, 또는 배치 파일이 아닙니다. error Command failed with exit code 1. info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.

이는 Windows 환경에서 TEXTDOMAIN을 환경 변수로 설정하는 방식이 Unix/Linux 환경과 다르기 때문입니다.
문제 핵심은 Windows CMD/PowerShell에서는 리눅스/유닉스 방식의 TEXTDOMAIN=wporg 같은 환경변수 선언+명령 실행이 안 돼서 발생하는 현상이야.

This seems to be an issue with using Windows, it thinks TEXTDOMAIN is a command rather than setting the variable. Maybe try set TEXTDOMAIN=”wporg” then composer exec update-configs ?

맞아, 슬랙에서 지적한 내용 정확해.
**Windows 명령 프롬프트(cmd.exe)**에서는 리눅스/유닉스처럼 TEXTDOMAIN=wporg command 식으로 명령어 앞에서 환경변수를 설정하는 방식이 안 먹혀.
그 대신 set TEXTDOMAIN=wporg 하고 나서 그 다음 줄에 명령어를 실행해야 돼.

하지만 지금 문제는 yarn을 통해 실행하면 내부에서 다시 TEXTDOMAIN=wporg composer exec ... 식으로 실행하면서, 윈도우가 그걸 “TEXTDOMAIN이라는 명령어”로 오해한다는 데 있어.

the dependencies seem to have installed correctly, the first error in red in your screenshot is expected sometimes, and running composer update fixes that.
종속성이 올바르게 설치된 것 같습니다. 스크린샷에서 빨간색 첫 번째 오류가 발생할 수 있으며, composer update를 실행하면 이 문제가 해결됩니다.

컴포저 업데이트는 할 필요가 있었는데 그래도 yarn setup:tools는 그대로임.

잠깐 정리

• 지금 에러는 Yarn이나 Composer 문제가 아님
• Windows의 TEXTDOMAIN=wporg composer exec update-configs 구문 처리 문제

방법 3: WSL 쓰기

가장 깔끔하게 해결하려면 WSL(Windows Subsystem for Linux)로 넘어가는 것도 방법임.
지금 워드프레스 공식 개발환경도 사실 유닉스 계열 기준으로 설계돼 있어서, wp-env나 Docker 연동도 WSL이 훨씬 깔끔하게 작동함.

WSL2 설치하고 우분투 설치해서 dev 폴더 복사해오고, 거기서

yarn setup:tools

치면 100% 깔끔하게 될 거임.

PS C:\Users\thaum\dev\wporg-main-2022> wsl --list --verbose
  NAME              STATE           VERSION
* docker-desktop    Running         2

현재 WSL에는 docker-desktop만 실행 중인 상태이고, Ubuntu나 다른 리눅스 배포판은 설치되지 않은 것 같습니다.
> dev home에서 Ubuntu 24.04 LTS 설치

WSL로 실행하더라도 윈도우 파일 시스템을 마운트해서 접근할 수는 있는데, 문제는
스크립트가 기대하는 실행 환경과 경로 해석 방식 때문이에요.

📌 정리하자면:

• 현재 프로젝트 경로가 C:\Users\thaum\dev\wporg-main-2022인데,
  WSL에서는 이걸 /mnt/c/Users/thaum/dev/wporg-main-2022로 접근할 수 있어요.
• 그러면 WSL 내 bash 환경에서 해당 디렉토리로 이동해서 composer, yarn, docker 같은 걸 실행하면
  Linux 기반 CLI 툴과 경로 규칙이 적용되기 때문에, 텍스트 도메인 설정 같은 것도 자연스럽게 먹힐 가능성이 높아짐.
• 게다가 워드프레스 wp-env 설정이나 composer.json 안에서도 bash나 /bin/sh 전제가 걸려있는 경우가 많아서
  윈도우 PowerShell이나 CMD에서는 에러나는 게 WSL에서는 정상 동작하는 경우가 꽤 있음.

---

윈도우에 설치된 php / node / yarn은 WSL에서 직접 쓸 수 없고,
WSL 안에 별도로 설치해줘야 해.

📦 WSL 안에 개발 툴 설치하기

📌 php 설치

sudo apt update
sudo apt install php-cli

📌 node & yarn 설치

Node 버전 매니저인 nvm 쓰는 게 좋아.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.5/install.sh | bash
source ~/.bashrc
nvm install --lts
nvm use --lts
npm install --global yarn

설치 확인

php -v
node -v
yarn -v
composer -V

composer도 없으면

sudo apt install composer

---

📌 그 다음에 다시 실행

설치 끝나면 아까 했던 것처럼

cd /mnt/c/Users/thaum/dev/wporg-main-2022
composer install
yarn
yarn setup:tools

이제 TEXTDOMAIN 에러 없이 정상 작동할 가능성이 높음.

---

📌 정리

지금까지 상황은

• 윈도우 → WSL로 옮긴 건 잘했음
• 근데 WSL 안에는 개발툴이 비어있어서 안 됐던 거
• 위 방법으로 설치하면 끝
• WSL 안에 설치한 php, node, yarn으로 /mnt/c/ 경로 파일 작업하는 거 가능함
• 단, 윈도우 쪽 프로그램이랑 환경이 달라서 버전 차이, 설정 차이 있을 수 있음
• 그리고 윈도우에서 돌리는 docker-desktop은 WSL에 docker 엔진 연결되므로, WSL 쪽 개발 환경은 docker 쓸 땐 편함

---

📌 정리

지금 상태는 yarn 실행은 됐는데 composer install이 덜 되어서 실행파일이 없어서 생긴 문제.
composer install을 WSL 안에서 다시 돌리고 yarn setup:tools 다시 실행하면 해결.

---

오케이! 아주 잘했어.
결정적 단서가 나왔네.

Bourne-Again shell script, ASCII text executable, with CRLF line terminators

이게 문제야.
CRLF 👉 윈도우 줄바꿈 방식이고, WSL (리눅스)은 LF 줄바꿈을 기대해.
지금 WSL에서 저 쉘 스크립트 읽다가 CRLF 때문에 실행 못 하는 상황.

---

🔧 해결법 ① — 줄바꿈 변환

이 명령으로 LF로 변환해주자:

dos2unix /mnt/c/Users/thaum/dev/wporg-main-2022/vendor/wporg/wporg-repo-tools/bin/update-configs

만약 dos2unix가 없다면 먼저 설치:

sudo apt update && sudo apt install dos2unix

그리고 다시 실행해봐.

---

🔧 해결법 ② — 프로젝트 전체 CRLF → LF 변환 (추천)

사실 이 문제, wporg-main-2022 프로젝트를 git clone할 때 Windows용 줄바꿈(CRLF)으로 들어와서 그래.
아예 프로젝트 전체를 한 번에 변환하는 것도 가능:

find /mnt/c/Users/thaum/dev/wporg-main-2022 -type f -exec dos2unix {} +

한 번만 해두면 앞으로 이런 문제 안 생김.

---

📌 요약

• 지금 CRLF 줄바꿈 때문에 WSL에서 실행 불가
• dos2unix로 LF로 변환해주면 해결
• 가능하면 프로젝트 전체 변환해두는 게 나음

여기까지 하고 cmd랑 wsl ubuntu 번갈아가면서 작업해서 실행 성공했음.

---

yarn wp-env start랑 wp-env start — 이 차이를 확실하게 짚고 넘어가자!

📌 yarn wp-env start

→ yarn 명령어로 package.json 안에 정의된 스크립트를 실행하는 것.

예를 들어, package.json 안에 이렇게 돼 있다고 해보자:

"scripts": {
  "wp-env": "wp-env",
  "start": "wp-env start"
}

이 경우

yarn wp-env start

는

1. wp-env 명령어를 실행하는 게 아니라
2. yarn run wp-env를 실행해서 node_modules/.bin 경로에 있는 wp-env (혹은 글로벌 설치된 wp-env)를 찾아서
3. start 명령을 전달하는 것.

장점:

• 로컬 프로젝트마다 설치된 wp-env 버전을 사용할 수 있어. (node_modules/.bin)
• 전역 설치 안 해도 됨.

---

📌 wp-env start

→ 직접 wp-env 명령어 실행
이건 네 시스템에 글로벌로 설치된 wp-env를 의미함.

npm install -g @wordpress/env

이렇게 설치했을 때 가능하고,
이때는 OS의 PATH에 등록된 전역 위치에서 wp-env를 실행해.

단점:

• 프로젝트마다 버전이 달라도 무조건 전역 설치된 걸 씀.
• 의존성 충돌 가능성 있음.

---

📌 결론

yarn wp-env start	wp-env start
프로젝트 로컬에 설치된 wp-env 사용	글로벌 설치된 wp-env 사용
package.json 스크립트에 정의 가능	전역으로만 실행 가능
프로젝트마다 버전 관리 가능	시스템 하나로 통일

개발에서는 보통 yarn wp-env start 같은 방식으로
프로젝트 로컬 버전으로 통제하는 게 안전하고 권장돼.

---

현재 Composer에서 GitHub API 요청 횟수 제한이 초과되었기 때문에 패키지 정보를 가져오는 데 실패한 상태입니다. GitHub API의 요청 제한은 시간당 60회로 제한되며, 이 제한을 초과하면 일정 시간이 지나야 다시 요청할 수 있습니다. 그러나 이를 해결하려면 GitHub OAuth 토큰을 생성하여 API 요청을 인증된 상태로 보내는 방법이 있습니다.

해결 방법:

1. GitHub OAuth 토큰 생성: 먼저 GitHub에서 OAuth 토큰을 생성해야 합니다. 다음 링크로 가셔서 토큰을 생성할 수 있습니다: GitHub OAuth Token 생성 페이지
   • Token Description: Composer를 사용하는 날짜나 프로젝트와 관련된 설명을 입력할 수 있습니다.
   • Scopes: 공개 저장소만 접근하려면 아무 권한도 설정하지 않아도 되며, 비공개 저장소에 접근하려면 repo 권한을 선택해야 합니다.
2. 토큰 입력: 생성한 토큰을 복사한 후, Composer에서 요청이 있을 때 토큰을 입력합니다. 해당 요청이 나타날 때, “Token (hidden)” 부분에 복사한 토큰을 붙여넣고 엔터를 누릅니다.
3. OAuth 토큰 저장: 토큰은 C:/Users/thaum/AppData/Roaming/Composer/auth.json 파일에 저장되어, 이후 요청에 자동으로 사용됩니다. 따라서, 추가적인 인증 없이도 토큰을 사용할 수 있습니다.
4. 기타 방법:
   • 대기: GitHub API의 요청 제한이 초기화될 때까지 기다리는 방법도 있습니다. 1시간마다 제한이 리셋되므로, 해당 시간이 지나면 다시 시도할 수 있습니다.

요약:

1. GitHub OAuth 토큰을 생성하고,
2. Composer에서 요청 시 해당 토큰을 입력하면 API 요청 제한을 우회할 수 있습니다.
3. 또는 제한 시간이 지나길 기다린 후 다시 시도할 수도 있습니다.

New personal access token (classic)을 생성할 때 필요한 권한은 공개 저장소에 대한 접근 권한만 필요합니다. 따라서, 아래와 같은 권한만 선택하면 됩니다:

1. public_repo: 공개 저장소에 접근할 수 있는 권한을 제공합니다. 이 권한은 GitHub에서 공개 저장소를 사용할 때 필요한 최소 권한입니다.

이 외의 권한은 필요하지 않으므로, 기본적으로 public_repo만 선택하면 됩니다.

단계별 선택 방법:

1. Token description: 예를 들어, “Composer on Desktop-Jiwoon 2025-04-30 1803” 처럼 토큰의 용도를 설명하는 이름을 입력합니다.
2. Expiration: 토큰의 만료 날짜를 설정합니다. 일반적으로 “No expiration”을 선택할 수 있습니다.
3. Scopes 선택:
   • public_repo 선택
4. Generate token: 토큰을 생성한 후, 제공된 Token을 복사하여 Composer에서 입력하면 됩니다.

이렇게 선택 후, 생성된 토큰을 사용하여 Composer에서 인증을 진행하면 GitHub API 제한을 우회할 수 있습니다.