WordPress.org 사이트의 한국어 폰트 개선을 실험하기 위한 개발 세팅입니다.

2025년 5월 11일, 일요일

전체 맥락 및 환경 개요

이 환경은 Windows 11에서 WordPress.org 사이트의 한글화 및 CJK(중국어·일본어·한국어) 폰트 개선을 실험하기 위한 개발 세팅입니다.
CLI(Command Line Interface) 도구로는 cmd, WSL2/Ubuntu, Docker wp-env를, GUI 도구로는 Docker Desktop, GitHub Desktop을 사용합니다.
목적은 WordPress.org의 테마와 MU-Plugins(필수 플러그인) 개발 및 다국어(특히 한글) 지원 강화를 위한 테스트 환경 구축입니다.

환경 구성

사용된 주요 환경 및 도구는 다음과 같습니다:

운영체제: Windows 11
CLI (Command Line Interface):
- Windows Command Prompt (cmd)
- WSL2 (Ubuntu)
- Docker wp-env
GUI (Graphical User Interface):
- Docker Desktop
- GitHub Desktop

개발 환경 설정 및 명령어 분석

단계별 명령어 분석 및 설명

로그에 나타난 명령어들을 순서대로 분석하고 각 명령어의 의미와 역할을 설명하겠습니다.

1. 프로젝트 초기 설정 (wporg-main-2022)

cd C:\Users\thaum\dev
- 맥락: Windows 명령 프롬프트(cmd)에서 작업 디렉터리를 C:\Users\thaum\dev로 변경합니다.
- 의미와 역할: 앞으로 수행할 명령어들의 기준 경로를 설정합니다.
git clone https://github.com/Jiwoon-Kim/wporg-main-2022.git
- 맥락: GitHub에 있는 개인 저장소에서 wporg-main-2022 소스를 로컬 환경으로 복제합니다.
- 의미와 역할: Jiwoon-Kim 사용자의 wporg-main-2022라는 WordPress 테마 또는 프로젝트의 전체 소스 코드를 dev 폴더 하위에 다운로드합니다.
cd .\wporg-main-2022
- 맥락: 방금 복제한 프로젝트 폴더로 작업 디렉터리를 변경합니다.

(WSL2 환경에서)

cd /mnt/c/Users/thaum/dev/wporg-main-2022
- 맥락: WSL2(Ubuntu) 터미널에서 Windows의 프로젝트 경로로 작업 디렉터리를 변경합니다. WSL에서는 Windows의 C 드라이브가 /mnt/c로 마운트됩니다.
- 의미와 역할: 이후 WSL 환경에서 프로젝트 관련 작업을 수행하기 위함입니다.
yarn
- Node.js 기반 의존성(프론트엔드 빌드 도구 등) 설치.
- 맥락: WSL 환경에서 Yarn 패키지 매니저를 사용하여 프로젝트의 JavaScript 의존성을 설치합니다. package.json 파일에 명시된 패키지들을 다운로드하고 설정합니다.
- 의미와 역할: 프로젝트 실행 및 빌드에 필요한 JavaScript 라이브러리들을 준비합니다.
composer install
- PHP 기반 의존성(플러그인, 라이브러리 등) 설치.
- 맥락: WSL 환경에서 Composer를 사용하여 PHP 의존성을 설치합니다. composer.json 파일에 명시된 패키지들을 다운로드하고 설정합니다.
- 의미와 역할: 프로젝트 실행에 필요한 PHP 라이브러리들을 준비합니다.
composer update wporg/wporg-mu-plugins
- 맥락: wporg/wporg-mu-plugins라는 특정 Composer 패키지를 최신 버전으로 업데이트합니다.
- 의미와 역할: 해당 MU (Must-Use) 플러그인 패키지를 최신 상태로 유지합니다.
yarn setup:tools
- 맥락: package.json에 정의된 setup:tools라는 사용자 정의 Yarn 스크립트를 실행합니다.
- 의미와 역할: 프로젝트 개발에 필요한 추가적인 도구(예: 린터, 빌드 스크립트 등)나 환경 설정을 자동화하는 스크립트일 가능성이 높습니다.

Docker 기반 WordPress 실행

C:\Users\thaum\dev\wporg-main-2022>yarn wp-env start
- 맥락: Windows 명령 프롬프트에서 wp-env를 사용하여 WordPress 개발 환경을 시작합니다. wp-env는 Docker를 기반으로 로컬 WordPress 환경을 쉽게 구성하고 실행할 수 있게 해주는 도구입니다.
- 의미와 역할: Docker 컨테이너를 실행하여 WordPress 사이트를 로컬에서 접근 가능하도록 합니다.
- 출력 결과: wp-env가 성공적으로 시작되었음을 나타내는 로그가 출력됩니다.
root@Desktop-Jiwoon:/mnt/c/Users/thaum/dev/wporg-main-2022# dos2unix env/setup.sh
- 맥락: WSL 환경에서 env/setup.sh 파일의 줄바꿈 문자(line endings)를 DOS 형식(CRLF)에서 Unix 형식(LF)으로 변환합니다. Windows에서 편집된 쉘 스크립트는 WSL에서 실행 문제를 일으킬 수 있으므로 변환이 필요합니다.
- 의미와 역할: 쉘 스크립트가 WSL 환경에서 올바르게 실행되도록 보장합니다.
C:\Users\thaum\dev\wporg-main-2022>yarn setup:wp
- 맥락: package.json에 정의된 setup:wp라는 사용자 정의 Yarn 스크립트를 실행합니다.
- 의미와 역할: WordPress 설치, 초기 설정, 플러그인 활성화 등 WordPress 관련 설정을 자동화하는 스크립트일 가능성이 높습니다.
- 출력 결과: [main 2025-05-09T12:07:52.227Z] update#setState idle – 특정 업데이트 상태가 ‘idle'(유휴)로 설정되었음을 나타내는 로그입니다.

콘텐츠 임포트

yarn wp-env run cli php env/import-content.php --url "https://wordpress.org/wp-json/wp/v2/posts?context=wporg_export&per_page=50"
yarn wp-env run cli php env/import-content.php --url "https://wordpress.org/wp-json/wp/v2/pages?context=wporg_export&per_page=50"
- 맥락: wp-env 환경 내에서 PHP CLI (Command Line Interface)를 사용하여 env/import-content.php 스크립트를 실행합니다. --url 파라미터를 통해 WordPress.org 사이트의 REST API에서 게시물(posts)과 페이지(pages) 데이터를 가져와 로컬 개발 환경으로 가져옵니다.
- 의미와 역할: 실제 운영 중인 사이트의 콘텐츠를 개발 환경으로 가져와 테스트 및 개발의 현실성을 높입니다.
  → 윈도우 셸(CMD/PowerShell)에서는 인자를 감쌀 때 기본적으로 큰따옴표 사용. 작은따옴표는 문자열 인식을 잘 못하고 내부 문자열을 변수로 해석하려 할 수 있음.
  → 유닉스 계열 셸에서는 작은따옴표로 감싸면 문자열 안의 모든 특수문자와 변수 해석을 비활성화하기 때문에 더 안전함.

2. MU 플러그인 (wporg-mu-plugins) 설정

MU-Plugins 및 테마 빌드

cd /mnt/c/Users/thaum/dev/wporg-main-2022/source/wp-content/mu-plugins/wporg-mu-plugins
- 맥락: WSL 환경에서 wporg-mu-plugins 디렉터리로 이동합니다. 이 플러그인은 여러 WordPress.org 사이트에서 공통으로 사용되는 기능을 제공하는 것으로 보입니다.
- 의미와 역할: 해당 MU 플러그인과 관련된 작업을 수행하기 위함입니다.
composer update
- 맥락: 현재 디렉터리(wporg-mu-plugins)의 Composer 의존성을 업데이트합니다.
- 의미와 역할: MU 플러그인이 사용하는 PHP 라이브러리들을 최신 상태로 유지합니다.
yarn
- 맥락: 현재 디렉터리의 Yarn 의존성을 설치합니다.
- 의미와 역할: MU 플러그인이 사용하는 JavaScript 라이브러리들을 준비합니다.
dos2unix ./bin/build.js
- 맥락: bin/build.js 파일의 줄바꿈 문자를 Unix 형식으로 변환합니다.
- 의미와 역할: JavaScript 빌드 스크립트가 WSL 환경에서 올바르게 실행되도록 합니다.
yarn build
- 맥락: MU 플러그인의 빌드 스크립트를 실행합니다. 주로 JavaScript 및 CSS 파일들을 컴파일하고 압축하는 작업을 수행합니다.
- 의미와 역할: 플러그인에서 사용될 정적 애셋(asset)들을 생성합니다.
- 출력 결과: Couldn't find block.json for screenshot-preview – screenshot-preview라는 블록의 block.json 파일을 찾을 수 없다는 오류 메시지입니다. 이는 특정 Gutenberg 블록 설정 파일이 누락되었거나 경로가 잘못되었음을 의미합니다.
- 특정 블록의 메타파일이 누락된 상태이나, 전체 빌드는 정상 진행됨.
yarn workspaces run build
- 맥락: Yarn workspaces 기능을 사용하여 프로젝트 내의 모든 하위 패키지/워크스페이스에 대해 build 스크립트를 실행합니다.
- 의미와 역할: 모노레포(monorepo) 구조에서 여러 패키지를 한 번에 빌드할 때 유용합니다.
npx browserslist@latest --update-db
- 맥락: browserslist 데이터베이스를 최신 버전으로 업데이트합니다. browserslist는 Autoprefixer나 Babel과 같은 도구들이 어떤 브라우저 버전을 대상으로 코드를 변환하거나 폴리필(polyfill)을 적용할지 결정하는 데 사용됩니다.
- 의미와 역할: 최신 브라우저 호환성 정보를 유지하여 빌드 결과물의 품질을 높입니다.
yarn workspaces run build
- 맥락: 다시 한번 모든 워크스페이스의 빌드 스크립트를 실행합니다. browserslist 업데이트 후 변경 사항을 반영하기 위함일 수 있습니다.

3. 상위 테마 (wporg-parent-2021) 설정 및 wp-env 재구성

cd C:\Users\thaum\dev
git clone https://github.com/WordPress/wporg-parent-2021.git Jiwoon-Kim/wporg-parent-2021
- 맥락: WordPress.org의 상위 테마로 사용될 wporg-parent-2021 저장소를 복제합니다.
- 의미와 역할: 하위 테마(wporg-main-2022)가 이 상위 테마의 기능을 상속받거나 확장할 수 있도록 준비합니다.
C:\Users\thaum\dev\wporg-main-2022\.wp-env.override.json 파일 생성, 내용 수정
- 여러 테마를 동시에 테스트할 수 있도록 테마 경로를 지정.
- 맥락: wp-env의 설정을 덮어쓰는 .wp-env.override.json 파일을 수정하여 여러 테마를 wp-env 환경에 포함시킵니다.
- 의미와 역할: wporg, wporg-main, wporg-main-2022, wporg-parent-2021 테마들을 로컬 개발 환경에서 함께 테스트할 수 있도록 설정합니다.

{
    "themes": [
	    "./source/wp-content/themes/wporg",
	    "./source/wp-content/themes/wporg-main",
	    "./source/wp-content/themes/wporg-main-2022",
	    "../wporg-parent-2021/source/wp-content/themes/wporg-parent-2021"
    ]
}

yarn wp-env stop
yarn wp-env start –update
- 맥락: wp-env 환경을 중지했다가 다시 시작합니다.
- 의미와 역할: .wp-env.override.json 파일의 변경된 설정을 적용합니다.

4. WordPress 관리자 설정 및 국제화

http://localhost:8888/wp-admin/ 접속 후 설정
- 맥락: 웹 브라우저에서 로컬 WordPress 관리자 페이지에 접속하여 사이트 언어를 한국어로 설정하고, 번역 업데이트를 수행합니다.
- 의미와 역할: 개발 환경의 WordPress 사이트를 한국어 환경으로 설정합니다.
  - http://localhost:8888/wp-admin/options-general.php
  - Site Language 한국어(korean)
  - http://localhost:8888/wp-admin/update-core.php
  - http://localhost:8888/wp-admin/update-core.php?action=do-translation-upgrade
테마 언어 파일 수동 배치
- Create a folder source/wp-content/languages/themes/ 경로에 wporg-ko_KR.mo 파일을 위치시키는 것을 목표로 하는 것으로 보입니다.
- Go to https://translate.wordpress.org/projects/meta/wordpress-org/
  - Translations < Korean < WordPress.org < GlotPress
- 맥락: WordPress 테마의 한국어 번역 파일을 직접 추가합니다.
- 의미와 역할: 테마의 텍스트가 한국어로 표시되도록 합니다.
- 페이지 하단으로 스크롤하여 번역 파일을 .mo 파일로 내보냅니다.
- 다운로드한 파일의 이름을 wporg-{locale}.mo 로 변경합니다. (e.g. wporg-ko_KR.mo)
- 파일을 소스/wp-콘텐츠/언어/테마 폴더로 이동합니다.
- .wp-env.override.json 파일을 만들거나 엽니다.
- 새 언어 폴더를 포함하도록 매핑mappings 업데이트

{
  "themes": [
    "./source/wp-content/themes/wporg",
    "./source/wp-content/themes/wporg-main",
    "./source/wp-content/themes/wporg-main-2022",
    "../wporg-parent-2021/source/wp-content/themes/wporg-parent-2021"
  ],
  "mappings": {
    "wp-content/languages": "./source/wp-content/languages"
  }
}

C:\Users\thaum\dev\wporg-main-2022\.wp-env.override.json 파일 내용 추가 수정
- 맥락: "mappings" 설정을 추가하여 호스트의 source/wp-content/languages 디렉터리를 Docker 컨테이너 내의 wp-content/languages 경로로 매핑합니다.
- 의미와 역할: 로컬에서 수정한 언어 파일이 Docker 환경 내의 WordPress에서 올바르게 인식되도록 합니다.
yarn wp-env stop
yarn wp-env start --update
- 맥락: wp-env 환경을 중지하고, Docker 이미지 및 컨테이너를 업데이트하면서 다시 시작합니다.
- 의미와 역할: 변경된 mappings 설정을 포함하여 환경 구성을 최신 상태로 적용합니다.
WordPress 관리자 페이지에서 추가 설정 (options-reading.php)
- 맥락: 홈페이지를 ‘home’으로 설정합니다.
- 의미와 역할: 사이트의 첫 화면으로 특정 페이지를 지정합니다.
- http://localhost:8888/wp-admin/options-reading.php
- homepage: home

5. Git 브랜치 작업 (wporg-mu-plugins 및 wporg-parent-2021) – 한국어 폰트 적용 관련

작업 맥락 및 목표

목적: WordPress.org의 MU-Plugins 및 Parent 테마에 한국어 폰트 최적화를 적용하기 위해 add/korean-font 브랜치를 활용한 Git 워크플로우 수행.
환경: Windows 11 + WSL2/Ubuntu + Docker(wp-env), GitHub 저장소 포크 및 원격 브랜치 관리.

이 부분은 주로 특정 기능(한국어 폰트 적용)을 위한 브랜치를 가져오고, 원격 저장소 설정을 관리하는 과정입니다.

`wporg-mu-plugins` 저장소 작업:

cd C:\Users\thaum\dev\wporg-main-2022\source\wp-content\mu-plugins\wporg-mu-plugins
git remote -v: 현재 설정된 원격 저장소 목록을 확인합니다.
git branch -a: 로컬 및 원격의 모든 브랜치 목록을 확인합니다.

1.1 원격 저장소 추가 및 브랜치 가져오기

git remote add jiwoon https://github.com/Jiwoon-Kim/wporg-mu-plugins.git
- jiwoon이라는 이름으로 새로운 원격 저장소 (Jiwoon-Kim 사용자의 포크된 저장소)를 추가합니다.
git fetch jiwoon add/korean-font:add/korean-font
- jiwoon 원격 저장소의 add/korean-font 브랜치를 가져와서 로컬에 동일한 이름의 브랜치를 생성합니다.
목적: 개인 포크 저장소에서 add/korean-font 브랜치를 로컬로 가져옴.
결과:
- jiwoon 원격이 추가되고, add/korean-font 브랜치가 로컬에 생성됨.
- git branch -a 출력에서 remotes/jiwoon/add/korean-font 확인 가능.

1.2 작업 중인 변경사항 임시 저장

git status: 현재 작업 디렉터리의 상태를 확인합니다. composer.lock 등 여러 파일이 변경된 상태로 나타납니다.
git stash push -m "vendor & lockfile 변경 임시 저장":
- vendor 디렉터리 및 lock 파일들의 변경 사항을 임시로 저장(stash)합니다. 이는 주로 패키지 매니저에 의해 자동으로 관리되는 파일들이므로, 브랜치 변경 전 현재 작업 내용을 잠시 치워두는 것입니다.

1.3 브랜치 전환 및 원격 추적 설정

git checkout add/korean-font: add/korean-font 브랜치로 전환합니다.
git remote show origin: origin 원격 저장소의 상세 정보를 보여줍니다. 이 시점에서 origin의 Fetch URL이 Jiwoon-Kim의 저장소로 변경된 것으로 보입니다.
git push --set-upstream jiwoon add/korean-font: 로컬의 add/korean-font 브랜치를 jiwoon 원격 저장소의 add/korean-font 브랜치로 푸시하고, 업스트림(추적) 브랜치로 설정합니다.
목적: add/korean-font 브랜치로 전환하고 개인 저장소에 푸시.
결과:
- branch 'add/korean-font' set up to track 'jiwoon/add/korean-font'로 원격 추적 활성화.
- GitHub에서 개인 저장소에 브랜치 반영 확인 가능.

`wporg-parent-2021` 저장소 작업:

cd C:\Users\thaum\dev\wporg-parent-2021
git remote -v, git branch -a 등으로 현재 상태 확인
git checkout add/korean-font: add/korean-font 브랜치로 전환합니다. 해당 브랜치는 이미 upstream/add/korean-font (WordPress 공식 저장소의 브랜치로 추정)와 동일한 최신 상태입니다.

6. 로컬 서버 접속 시 오류 메시지 확인

`http://localhost:8888/` 접속 시 다수의 PHP Notice 및 Warning 발생

Notice: 함수 WP_Block_Type_Registry::register이(가) 바르지 않게 호출됐습니다. 블록 유형 이름은 네임스페이스 접두어를 포함해야 합니다. 예: my-plugin/my-custom-block-type...
- 의미: Gutenberg 블록을 등록할 때 블록 이름에 네임스페이스(예: my-plugin/my-block)가 포함되어야 하는데, 그렇지 않아서 발생하는 알림입니다.
- 원인: 커스텀 블록 등록 시 namespace/block-name 형식 미준수.
- 해결: register_block_type('wporg/global-header') 형태로 수정 필요
Notice: wp_json_file_decode(): 파일이 존재하지 않습니다! [cite: 23, 25]
- 의미: block.json과 같은 JSON 파일을 읽어오려고 시도했으나 해당 파일이 없거나 경로가 잘못되어 발생하는 알림입니다. 앞서 yarn build 시 Couldn't find block.json for screenshot-preview 오류와 연관이 있을 수 있습니다.
Warning: filemtime(): stat failed for /var/www/html/wp-content/mu-plugins/wporg-mu-plugins/mu-plugins/blocks/global-header-footer/build/style.css...
- 의미: 특정 CSS 파일의 최종 수정 시간을 가져오려 했으나 파일이 존재하지 않거나 접근할 수 없어 발생하는 경고입니다. 빌드 과정에서 해당 CSS 파일이 정상적으로 생성되지 않았을 가능성이 있습니다.
- 원인: yarn build 실행 실패로 style.css 미생성.
- 해결: 빌드 스크립트 점검 및 block.json 파일 존재 확인
Warning: Cannot modify header information - headers already sent by...
- 의미: HTTP 헤더를 전송하기 전에 이미 페이지 내용(주로 오류 메시지)이 출력되어 발생하는 경고입니다. 위의 Notice나 Warning 메시지들 때문에 발생한 부수적인 문제입니다.
- 원인: PHP 파일 시작/종료 태그 외부에 공백 또는 출력 존재.
- 해결: <?php 전후 공백 제거 및 echo/print 사용 회피
http://localhost:8888/wp-admin/index.php 접속 시에도 유사한 오류 발생

7. `wporg-main-2022` 프로젝트의 Git 변경 사항 커밋

cd C:\Users\thaum\dev\wporg-main-2022
git status: composer.lock, env/setup.sh, package.json 파일이 수정된 것을 확인합니다. [cite: 33]
git add .: 변경된 모든 파일을 Staging Area로 추가합니다. [cite: 34]
- 출력 결과 (경고): LF will be replaced by CRLF – Git이 다음 번에 해당 파일들을 건드릴 때 줄바꿈 문자를 LF(Unix)에서 CRLF(Windows)로 변환할 것이라는 경고입니다. 이는 Git의 core.autocrlf 설정과 관련이 있습니다. [cite: 34]
.gitattributes 파일 생성 및 내용 추가 [cite: 34]
- * text=auto
- *.sh text eol=lf
- *.json text eol=lf
- *.lock text eol=lf
- 맥락: 파일 확장자별로 Git이 줄바꿈 문자를 처리하는 방식을 명시적으로 설정합니다. 쉘 스크립트(.sh), JSON 파일(.json), 락 파일(.lock)은 항상 LF(Unix) 줄바꿈을 사용하도록 지정합니다.
- 의미와 역할: 여러 운영체제에서 협업하거나 WSL과 Windows를 함께 사용할 때 발생할 수 있는 줄바꿈 문자 불일치 문제를 예방하고 일관성을 유지합니다.
root@Desktop-Jiwoon:/mnt/c/Users/thaum/dev/wporg-main-2022# dos2unix composer.lock env/setup.sh package.json [cite: 34]
root@Desktop-Jiwoon:/mnt/c/Users/thaum/dev/wporg-main-2022# dos2unix .gitattributes [cite: 34]
- 맥락: WSL 환경에서 해당 파일들의 줄바꿈 문자를 다시 한번 Unix 형식(LF)으로 명시적으로 변환합니다. git add . 시점의 경고와 .gitattributes 설정을 확실히 하기 위한 조치로 보입니다.
- 의미와 역할: Git 저장소에 커밋되는 파일들의 줄바꿈 형식을 LF로 통일합니다.
git commit -m "trunk: composer.lock, setup.sh, package.json 업데이트" [cite: 35]
- 맥락: Staging Area에 있는 변경 사항들을 “trunk: composer.lock, setup.sh, package.json 업데이트”라는 커밋 메시지와 함께 로컬 저장소에 기록합니다.
- 의미와 역할: 프로젝트의 주요 설정 파일 업데이트 내역을 버전 관리 시스템에 저장합니다.
- 출력 결과: 3 files changed, 14 insertions(+), 9 deletions(-), create mode 100644 .gitattributes – 변경된 파일 수와 내용, 그리고 .gitattributes 파일이 새로 생성되었음을 나타냅니다. [cite: 35]

전체적인 분석 및 총평

목표: WordPress.org 관련 테마 및 플러그인(특히 한국어 환경 및 CJK 폰트 관련)을 로컬 환경에서 개발하고 테스트하기 위한 환경 구축 과정입니다.
도구 활용: Windows와 WSL2의 장점을 혼합하여 사용하고 있으며, Docker(wp-env)를 통해 격리되고 일관된 WordPress 환경을 구성했습니다. Git을 이용한 버전 관리 및 협업 준비도 이루어지고 있습니다.
과정의 복잡성: 여러 저장소(테마, 상위 테마, MU 플러그인)를 다루고, 각 저장소의 의존성 관리(Yarn, Composer), 빌드 과정, wp-env 설정 변경 등 다소 복잡한 설정 단계를 거치고 있습니다. 이는 실제 대규모 WordPress 프로젝트 개발 환경에서 볼 수 있는 모습입니다.
주요 이슈:
- 줄바꿈 문자(Line Endings): Windows와 WSL(Linux) 환경을 혼용하면서 발생하는 줄바꿈 문자 불일치 문제가 지속적으로 나타나고 있으며, dos2unix와 .gitattributes를 통해 해결하려는 노력이 보입니다.
- Gutenberg 블록 관련 오류: block.json 파일 누락, 블록 등록 방식 오류, 관련 CSS 파일 누락 등의 PHP Notice 및 Warning이 발생하고 있습니다. 이는 주로 블록 빌드 과정의 문제이거나, wp-env 환경에서의 경로 문제일 수 있습니다. [cite: 22, 23, 24, 25, 26, 27, 28, 29, 30, 31, 32]

개선 사항 제안

줄바꿈 문자 일관성 확보:
- 프로젝트 시작 시점에 .gitattributes 파일을 명확히 설정하고 팀원 전체가 동일한 Git core.autocrlf 설정을 사용하도록 가이드하는 것이 좋습니다. (예: WSL/Linux/macOS는 input, Windows는 true 또는 모두 false로 하고 에디터에서 LF로 통일)
- 텍스트 에디터(VSCode 등)에서 기본 줄바꿈 문자를 LF로 설정하고, 저장 시 자동으로 LF로 변환하도록 설정하면 dos2unix 사용 빈도를 줄일 수 있습니다.
Gutenberg 블록 오류 해결:
- Couldn't find block.json for screenshot-preview 오류: screenshot-preview 블록의 block.json 파일이 실제로 존재하는지, 경로가 올바른지, 빌드 과정에서 정상적으로 포함되는지 확인해야 합니다. [cite: 2]
- WP_Block_Type_Registry::register 관련 Notice: 블록 등록 시 namespace/block-name 형식을 따르는지 코드 점검이 필요합니다. [cite: 22, 24, 26, 27, 29, 31]
- CSS 파일 filemtime() Warning: 해당 CSS 파일이 yarn build 과정에서 정상적으로 생성되는지 확인하고, wp-env 환경 내에서 파일 경로가 올바른지 점검해야 합니다. [cite: 26] Docker 컨테이너 내부에서 직접 파일 경로를 확인해보는 것도 도움이 됩니다 (wp-env run cli bash 후 ls 명령어 사용).
wp-env 설정 및 재시작:
- .wp-env.override.json 파일 변경 후에는 항상 yarn wp-env start --update 또는 yarn wp-env restart --update를 사용하여 변경 사항이 Docker 컨테이너에 제대로 반영되도록 하는 것이 좋습니다. --update 플래그는 Docker 이미지나 구성이 변경되었을 때 유용합니다.
Git 원격 저장소 관리 전략:
- wporg-mu-plugins 저장소에서 origin 원격의 URL이 중간에 변경된 것으로 보입니다. 일반적으로 자신의 포크(fork) 저장소를 origin으로, 원본 공식 저장소를 upstream으로 명명하여 사용하는 것이 혼동을 줄이는 데 도움이 됩니다. 현재 composer라는 이름의 remote도 존재하는데, 이는 Composer가 의존성으로 git 저장소를 추가할 때 자동으로 생성하는 이름일 수 있습니다. 원격 저장소 명명 규칙을 일관되게 가져가는 것이 좋습니다.
의존성 관리 및 브랜치 전환:
- git stash를 사용하여 vendor 및 lockfile 변경 사항을 임시 저장하는 것은 유효하지만[cite: 7], 이 파일들은 보통 패키지 매니저(composer, yarn)가 관리하므로 직접 수정하는 것은 권장되지 않습니다. 브랜치 전환 전에 composer.json이나 package.json의 변경 사항을 커밋하거나 폐기한 후, 새 브랜치에서 해당 패키지 매니저의 install 또는 update 명령을 다시 실행하는 것이 더 깔끔한 방법일 수 있습니다.
스크립트 활용:
- 반복적인 설정 과정(예: dos2unix 여러 번 실행, wp-env 재시작 등)은 하나의 쉘 스크립트로 통합하여 관리하면 실수를 줄이고 효율성을 높일 수 있습니다.
빌드 순서:
- yarn workspaces run build 실행 후 npx browserslist@latest --update-db를 실행하고 다시 yarn workspaces run build를 실행하는 부분은[cite: 2], browserslist 데이터베이스 업데이트가 실제 빌드 결과물에 즉각적인 영향을 주지 않는다면 두 번째 빌드는 불필요할 수 있습니다.

구현 과정에서 목적까지 가는데 불필요한 과정이 있었는지?

composer update wporg/wporg-mu-plugins 후 다시 wporg-mu-plugins 디렉토리에서 composer update 실행: [cite: 2]
- 만약 wporg-mu-plugins가 메인 프로젝트(wporg-main-2022)의 vendor 디렉터리 내 하위 모듈로 관리된다면 첫 번째 업데이트로 충분할 수 있습니다. 하지만 로그 후반부를 보면 wporg-mu-plugins를 별도의 Git 저장소처럼 다루며 내부에서 직접 의존성 관리 및 빌드를 수행하므로, 두 번째 composer update는 해당 플러그인을 직접 개발/수정하는 상황에서는 필요했을 수 있습니다. 이것이 중복인지 아닌지는 프로젝트의 정확한 구조와 의존성 관리 전략에 따라 달라집니다.
dos2unix의 반복적인 사용: [cite: 2, 34]
- .gitattributes 설정과 Git core.autocrlf 설정을 프로젝트 초기에 올바르게 구성하고, 모든 개발자가 에디터 설정을 통일한다면 수동으로 dos2unix를 여러 번 실행하는 과정을 줄일 수 있습니다. git add . 이후에 발생한 경고에 대한 대응으로 dos2unix를 실행한 것은 [cite: 34] 타당해 보이지만, 근본적인 설정을 점검하여 예방하는 것이 더 효율적입니다.
yarn workspaces run build 두 번 실행: [cite: 2]
- browserslist 업데이트 후 즉시 다시 빌드하는 것이 반드시 필요한지 검토가 필요합니다. 변경된 browserslist가 빌드 결과에 큰 차이를 만들지 않거나, 다른 코드 변경 없이 browserslist만 업데이트된 경우라면 두 번째 빌드는 생략 가능할 수 있습니다.

전반적으로 복잡한 WordPress 개발 환경을 체계적으로 구축하려는 노력이 돋보입니다. 다만, 몇몇 부분에서 발생하는 오류와 반복적인 작업들은 설정을 표준화하고 자동화함으로써 개선할 여지가 있습니다.

구체적인 개선 방안, 업데이트/디버깅 전략, 빌드 문제 해결 및 최적화 제안 (2025년 5월 10일 현 시점 기준)

제공해주신 로그를 바탕으로 현 시점에서 개발 환경을 개선하고, 발생 가능한 문제를 해결하며, 전반적인 워크플로우를 최적화할 수 있는 구체적인 방안들을 제안합니다.

1. 즉시 적용 가능한 구체적인 개선 사항

줄바꿈 문자(Line Endings) 일관성 강화:

.gitattributes 파일 활용: 현재 .gitattributes 파일에 주요 확장자별 eol=lf 설정이 되어 있는 것은 매우 좋습니다. 이 파일이 프로젝트 루트에 있는지 확인하고, 팀 전체에 이 설정을 공유하세요.

* text=auto eol=lf
*.bat eol=crlf
# 필요에 따라 다른 Windows 특정 파일 확장자 추가

(* text=auto eol=lf로 설정하면 Git이 대부분의 텍스트 파일을 LF로 통일하되, 필요한 경우 CRLF로 자동 변환합니다. Windows 전용 스크립트 등은 eol=crlf로 명시하는 것이 좋습니다.)
텍스트 에디터 설정 통일: 사용하시는 텍스트 에디터(예: VSCode)에서 기본 줄바꿈 문자를 LF로 설정하고, 저장 시 자동으로 LF로 변환하도록 설정합니다. (VSCode의 경우, 설정에서 Files: Eol을 \n으로 변경)
dos2unix 최소화: 위 설정들이 잘 적용되면 dos2unix 명령어의 수동 사용 빈도가 크게 줄어들 것입니다.

Git 원격 저장소 이름 표준화:

현재 wporg-mu-plugins 저장소에서 origin과 jiwoon 원격이 혼용되고, composer라는 원격도 보입니다. 혼동을 줄이기 위해 다음과 같이 표준화하는 것을 권장합니다.
- origin: 자신의 개인 포크(fork) 저장소 (예: https://github.com/Jiwoon-Kim/wporg-mu-plugins.git)
- upstream: 원본 공식 저장소 (예: https://github.com/WordPress/wporg-mu-plugins.git)
실행 예시 (wporg-mu-plugins 디렉터리에서):

# 현재 origin의 URL 확인 및 변경 (필요시)
git remote get-url origin
# 만약 origin이 공식 저장소를 가리키고 있다면, jiwoon (개인 포크)으로 변경
# git remote set-url origin https://github.com/Jiwoon-Kim/wporg-mu-plugins.git

# upstream 추가 (WordPress 공식 저장소)
git remote add upstream https://github.com/WordPress/wporg-mu-plugins.git

# 확인
git remote -v

이렇게 하면 git fetch upstream으로 공식 변경 사항을 가져오고, git push origin <branch_name>으로 개인 포크에 푸시하는 명확한 워크플로우가 가능해집니다.

PHP 오류/알림 해결 (가장 시급):

Couldn't find block.json for screenshot-preview 및 wp_json_file_decode(): 파일이 존재하지 않습니다!:
- wporg-mu-plugins 또는 관련 테마 내 screenshot-preview 블록의 block.json 파일이 실제로 해당 경로에 있는지, 파일명이 정확한지 확인합니다. (대소문자 구분)
- yarn build 또는 yarn workspaces run build 실행 시 screenshot-preview 블록 관련 빌드 로그에 오류가 없는지 상세히 확인합니다.
- 필요하다면 해당 블록의 block.json 내용을 검토하여 문법 오류가 없는지 확인합니다.
WP_Block_Type_Registry::register 알림:
- 로그에 나온 것처럼 블록 등록 시 my-plugin/my-custom-block-type 형식으로 네임스페이스를 포함해야 합니다. 관련 PHP 코드에서 블록 등록 부분을 찾아 수정합니다.
- 예시: register_block_type( 'screenshot-preview', ... ); -> register_block_type( 'wporg/screenshot-preview', ... ); (네임스페이스는 적절히 변경)
filemtime(): stat failed for ... style.css 경고:
- 해당 CSS 파일 (global-header-footer/build/style.css)이 빌드 과정에서 정상적으로 생성되는지 확인합니다.
- wp-env 환경 내에서 해당 파일 경로가 올바른지 확인합니다. (wp-env run cli bash로 컨테이너 접속 후 ls -la /var/www/html/wp-content/mu-plugins/wporg-mu-plugins/mu-plugins/blocks/global-header-footer/build/)
- 빌드 스크립트나 webpack.config.js (또는 wordpress/scripts 설정)에서 CSS 파일 출력 경로가 올바르게 설정되어 있는지 확인합니다.

2. 업데이트, 업그레이드, 디버깅 전략

의존성 업데이트 (Update):
- Node.js 패키지 (Yarn):
  - 주기적으로 yarn outdated 명령으로 업데이트 가능한 패키지를 확인합니다.
  - yarn upgrade-interactive --latest 명령으로 선택적으로 패키지를 최신 버전으로 업데이트합니다.
  - yarn.lock 파일 변경 사항을 커밋합니다.
- PHP 패키지 (Composer):
  - composer outdated 또는 composer show -l로 업데이트 가능한 패키지를 확인합니다.
  - composer update <vendor/package> 형태로 특정 패키지를 업데이트하거나, composer update로 composer.json에 명시된 버전 제약 조건 내에서 업데이트합니다.
  - 업데이트 전 주요 변경 사항(breaking changes)은 해당 패키지의 릴리즈 노트를 확인하는 것이 중요합니다.
  - composer.lock 파일 변경 사항을 커밋합니다.
도구 및 환경 업그레이드 (Upgrade):
- wp-env: @wordpress/env 패키지를 글로벌 또는 프로젝트별로 업데이트합니다.

# 글로벌 설치 시
npm install -g @wordpress/env@latest
# 프로젝트 로컬 설치 시 (package.json에 있다면)
yarn upgrade @wordpress/env --latest

Bash# 글로벌 설치 시 npm install -g @wordpress/env@latest # 프로젝트 로컬 설치 시 (package.json에 있다면) yarn upgrade @wordpress/env --latest
Node.js, Yarn, Composer: 각 도구의 공식 문서를 참고하여 최신 안정 버전으로 업그레이드합니다. (Node.js는 nvm 사용 권장)
Docker Desktop, WSL2: 주기적으로 최신 버전으로 업데이트하여 성능 개선 및 버그 수정을 반영합니다.
디버깅 전략:
- WordPress 디버깅 활성화:
  - wp-env 환경의 wp-config.php 파일에 다음 상수를 정의하거나 수정합니다. wp-env는 .wp-env.override.json 또는 .wp-env.json의 config 옵션을 통해 wp-config.php 상수를 설정할 수 있습니다. JSON// .wp-env.override.json { // ... other configs "config": { "WP_DEBUG": true, "WP_DEBUG_LOG": true, // /wp-content/debug.log 파일에 오류 기록 "WP_DEBUG_DISPLAY": false, // 화면에 오류 메시지 표시 여부 (개발 중에는 true도 유용) "SCRIPT_DEBUG": true // 압축되지 않은 JS/CSS 파일 사용 } } 설정 후 yarn wp-env stop && yarn wp-env start --update로 환경 재시작.
- 브라우저 개발자 도구: 웹 브라우저의 개발자 도구(F12)의 ‘Console’ 탭에서 JavaScript 오류를, ‘Network’ 탭에서 파일 로딩 문제 등을 확인합니다.
- wp-env 및 Docker 로그:
  - wp-env run cli bash로 WordPress 컨테이너에 접속 후, Apache/PHP-FPM 로그 파일 확인 (/var/log/apache2/error.log 등, 환경에 따라 다름).
  - docker ps로 실행 중인 컨테이너 ID 확인 후, docker logs <container_id_or_name>로 Docker 컨테이너의 표준 출력/오류 로그를 확인합니다. (특히 PHP 오류)
- 빌드 로그 상세 분석: yarn build 또는 yarn workspaces run build 실행 시 출력되는 모든 메시지, 특히 오류나 경고 메시지를 주의 깊게 확인합니다.
- Xdebug (고급 PHP 디버깅):
  - wp-env는 Xdebug를 지원합니다. .wp-env.override.json에 Xdebug 설정을 추가할 수 있습니다. JSON// .wp-env.override.json { // ... "env": { "development": { "xdebug": true // 또는 구체적인 Xdebug 설정 } } }
  - VSCode 등의 에디터에서 PHP Xdebug 확장 기능을 설치하고 설정하여 단계별 디버깅을 활용합니다.

3. 빌드 내용 꼬임 및 충돌 해결, 최적화

빌드 문제 발생 시 확인 및 해결 단계:
1. 변경 사항 격리: 문제가 발생하기 직전의 변경 사항을 되돌려보고(git checkout), 특정 커밋이나 변경 사항이 원인인지 파악합니다.
2. 캐시 및 빌드 결과물 삭제 (클린 빌드):
  - Node.js/Yarn: Bash# 각 프로젝트/워크스페이스 루트에서 실행 rm -rf node_modules rm -rf build dist # 또는 빌드 결과물이 저장되는 다른 폴더 yarn cache clean # Yarn 캐시 정리 (선택적) yarn install yarn build
  - Composer: Bash# 각 프로젝트/워크스페이스 루트에서 실행 rm -rf vendor composer clear-cache # Composer 캐시 정리 composer install
3. 의존성 충돌 확인:
  - Yarn: yarn why <package_name> 명령으로 특정 패키지가 여러 버전으로 중복 설치되었는지, 어떤 의존성 트리에 의해 설치되었는지 확인합니다.
  - Composer: composer prohibits <package_name> <version>와 같은 메시지를 통해 버전 충돌을 파악할 수 있습니다. composer.json의 버전 제약 조건을 수정하거나, 충돌을 일으키는 패키지를 업데이트/다운그레이드하여 해결합니다.
4. 점진적 빌드 및 테스트: 문제가 되는 부분을 찾기 위해, 전체 빌드 대신 특정 모듈이나 블록만 개별적으로 빌드해보거나(스크립트가 지원한다면), 관련 없는 부분은 일시적으로 비활성화하고 테스트합니다.
5. wp-env 환경 완전 초기화:
  - yarn wp-env destroy 명령으로 Docker 볼륨을 포함한 모든 환경을 삭제합니다.
  - 이후 yarn wp-env start --update로 완전히 새로운 환경을 구축합니다. (주의: DB 내용도 초기화될 수 있으므로 백업 필요시 수행)
빌드 및 개발 환경 최적화:
1. 빌드 시간 단축:
  - Webpack 캐시 활용: @wordpress/scripts는 내부적으로 Webpack을 사용하며, Webpack은 기본적으로 파일 시스템 캐시를 활용하여 변경되지 않은 모듈의 재빌드 시간을 줄입니다. 특별한 설정 없이도 어느 정도 효과가 있지만, 대규모 프로젝트에서는 Webpack 설정을 직접 커스터마이징하여 캐시 전략을 최적화할 수 있습니다 (고급).
  - 변경된 워크스페이스만 빌드: Yarn workspaces를 사용 중이므로, lerna와 같은 도구를 함께 사용하여 변경된 패키지만 빌드하는 전략을 고려할 수 있습니다. (lerna run build --since main)
2. wp-env 성능:
  - Docker Desktop 설정에서 WSL2 백엔드가 사용 중인지 확인하고, CPU, 메모리, 디스크 공간 등 Docker에 할당된 리소스가 충분한지 확인합니다. Windows에서는 파일 I/O 성능이 WSL2 내부보다 느릴 수 있으므로, 가능한 한 WSL2 내부에서 프로젝트 파일을 관리하고 명령을 실행하는 것이 좋습니다.
3. 자동화 스크립트 작성:
  - 자주 사용하는 명령어 조합(예: 클린 빌드 후 환경 재시작)은 package.json의 scripts에 추가하거나, 별도의 쉘 스크립트 파일로 만들어두면 편리합니다. JSON// package.json 예시 "scripts": { "dev": "yarn wp-env start", "build": "yarn workspaces run build", "clean-build": "rm -rf node_modules yarn.lock && rm -rf build dist && yarn install && yarn build", "wp-restart": "yarn wp-env stop && yarn wp-env start --update" }
4. 불필요한 의존성 제거:
  - 주기적으로 npm-check-unused (npm) 또는 depcheck (yarn/npm) 같은 도구를 사용하여 프로젝트에서 더 이상 사용되지 않는 패키지를 찾아 제거합니다.
5. 활성 개발 중인 부분만 wp-env에 포함:
  - .wp-env.override.json의 themes나 plugins 배열에 현재 작업 중이지 않은 항목이 많다면, 로딩 시간이나 리소스 사용에 영향을 줄 수 있습니다. 작업에 필요한 최소한의 항목만 포함하도록 조절하는 것도 방법입니다.

이 제안들이 현재 겪고 계신 문제를 해결하고 개발 환경을 더욱 효율적으로 만드는 데 도움이 되기를 바랍니다. 특히 PHP 오류/알림 해결을 최우선으로 진행하시는 것이 좋습니다.

Last Updated: 2025년 05월 11일1 Comment

onthispost

Last Updated: 2025년 05월 11일Categories: 워드프레스Tags: 174, 175, 685Views: 93글

One Comment

WordPress.org 개발 환경 설정 및 한국어 폰트 적용 가이드 (초보자도 따라 할 수 있게!) - Travel in BUSAN | 부산을 여행하다 2025년 05월 13일 at 오후 10:25 - Reply

[…] WordPress.org 사이트의 한국어 폰트 개선을 실험하기 위한 개발 세팅입니다. […]

Don’t miss

현재와 그 너머(2020~2024)
2025.05.19.월요일

트래블로그
2025.05.19.월요일
쿠팡 파트너스
2025.05.19.월요일
청춘의 시작(2015~2016)
2024.03.28.목요일
자료정리
2025.05.19.월요일
유용한 정보
2024.03.29.금요일

Blog

최신 글

my blog

by topics

Portfolio

Categories

01

Expertise

Brand Identity

01

Digital Marketing

02

Content Strategy

03

E-commerce

04

App Development

05

화룡진월

흑혈천구

천빙설화

백천풍운

문의하기

WordPress.org 사이트의 한국어 폰트 개선을 실험하기 위한 개발 세팅입니다.

전체 맥락 및 환경 개요

환경 구성

개발 환경 설정 및 명령어 분석

단계별 명령어 분석 및 설명

1. 프로젝트 초기 설정 (wporg-main-2022)

(WSL2 환경에서)

Docker 기반 WordPress 실행

콘텐츠 임포트

2. MU 플러그인 (wporg-mu-plugins) 설정

MU-Plugins 및 테마 빌드

3. 상위 테마 (wporg-parent-2021) 설정 및 wp-env 재구성

4. WordPress 관리자 설정 및 국제화

5. Git 브랜치 작업 (wporg-mu-plugins 및 wporg-parent-2021) – 한국어 폰트 적용 관련

작업 맥락 및 목표

wporg-mu-plugins 저장소 작업:

1.1 원격 저장소 추가 및 브랜치 가져오기

1.2 작업 중인 변경사항 임시 저장

1.3 브랜치 전환 및 원격 추적 설정

wporg-parent-2021 저장소 작업:

6. 로컬 서버 접속 시 오류 메시지 확인

http://localhost:8888/ 접속 시 다수의 PHP Notice 및 Warning 발생

7. wporg-main-2022 프로젝트의 Git 변경 사항 커밋

전체적인 분석 및 총평

개선 사항 제안

구현 과정에서 목적까지 가는데 불필요한 과정이 있었는지?

구체적인 개선 방안, 업데이트/디버깅 전략, 빌드 문제 해결 및 최적화 제안 (2025년 5월 10일 현 시점 기준)

1. 즉시 적용 가능한 구체적인 개선 사항

2. 업데이트, 업그레이드, 디버깅 전략

3. 빌드 내용 꼬임 및 충돌 해결, 최적화

onthispost

One Comment

댓글 남기기응답 취소

Don’t miss

Related Posts

2015 라인드로잉, 점묘화

2015 아크릴화 습작, 색연필 묘사

2015 동물 일러스트

2015 신선로 리플렛 디자인

2015 아이덴티티 디자인

2016 베르사체 패키지 디자인

2015 GTQ 연습

2016 다식 패키지 디자인

2016 부산소방안전체험관 CI

2020 로고디자인

Insights Hub

전문 분야 & 서비스

디자인과 디지털 솔루션의 모든 것

산업 디자인

일러스트 & 그래픽 디자인

웹 & 디지털 솔루션

콘텐츠 제작 & 전략

AI 프롬프트 엔지니어링

궁금한 점이 있거나 협업을 원하신다면 언제든지 연락 주세요!

프로젝트에 대해 알려주세요.

Travel-in-Busan은 글로벌화 시대에 국가와 민족을 초월한 세계시민연대를 꿈꾸며, AI 시대를 대비해 디지털 네트워크 환경 속 개인의 성장을 지향합니다.

1. 개인 철학 및 웹사이트 목적:

`wporg-mu-plugins` 저장소 작업:

`wporg-parent-2021` 저장소 작업:

`http://localhost:8888/` 접속 시 다수의 PHP Notice 및 Warning 발생

7. `wporg-main-2022` 프로젝트의 Git 변경 사항 커밋

전문 분야 &
서비스