docs: [standards] PDF 경량화 설정 및 font-weight 주의사항 추가
- 폰트 서브셋팅(enable_font_subsetting) 필수 설정 추가 - font-weight 800 이상 사용 금지 규칙 추가 - 섹션 번호 정리 (5.경량화, 6.수정가이드, 7.긴급복구, 8.체크리스트)
This commit is contained in:
@@ -29,6 +29,8 @@ Failed to open stream: Permission denied
|
||||
✅ NanumGothic을 DomPDF에 등록하여 사용
|
||||
✅ 폰트 등록은 storage/fonts/에 캐시 (vendor/ 아님)
|
||||
✅ 자동 등록 패턴(ensureKoreanFont) 적용
|
||||
✅ font-weight는 normal/bold만 사용 (800 이상 금지 — DomPDF 미매칭으로 한글 깨짐)
|
||||
✅ 폰트 서브셋팅 활성화 (config/dompdf.php)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -51,7 +53,19 @@ $pdf = Pdf::loadView('view', $data)
|
||||
->setOptions(['isRemoteEnabled' => true]);
|
||||
```
|
||||
|
||||
### 2.3 DomPDF 미등록 폰트 사용 금지
|
||||
### 2.3 font-weight 800 이상 사용 금지
|
||||
|
||||
NanumGothic은 `normal`(400)과 `bold`(700) 두 가지 weight만 존재한다. `font-weight: 800` 이상을 지정하면 DomPDF가 매칭되는 폰트를 찾지 못해 해당 텍스트의 한글이 `?`로 깨진다.
|
||||
|
||||
```css
|
||||
/* ❌ DomPDF에서 한글 깨짐 — 800 weight에 매칭되는 폰트 없음 */
|
||||
h1 { font-weight: 800; }
|
||||
|
||||
/* ✅ bold(700)까지만 사용 */
|
||||
h1 { font-weight: bold; }
|
||||
```
|
||||
|
||||
### 2.4 DomPDF 미등록 폰트 사용 금지
|
||||
|
||||
DomPDF는 시스템 폰트를 자동으로 인식하지 않는다. `Malgun Gothic`, `Apple SD Gothic Neo` 등을 `font-family`에 지정해도 DomPDF가 찾지 못해 한글이 `???`로 깨진다.
|
||||
|
||||
@@ -189,7 +203,42 @@ storage/fonts/
|
||||
|
||||
---
|
||||
|
||||
## 5. 기존 코드 수정 가이드
|
||||
## 5. PDF 경량화 설정
|
||||
|
||||
### 5.1 배경 — 텍스트 PDF가 5MB
|
||||
|
||||
급여명세서 PDF(텍스트만, 1페이지)가 약 5MB로 생성되는 문제가 발생. 원인은 DomPDF가 NanumGothic 폰트 파일 전체(수천 개 한글 글리프 포함)를 PDF에 임베딩하기 때문이다.
|
||||
|
||||
### 5.2 폰트 서브셋팅 (필수)
|
||||
|
||||
`config/dompdf.php`에서 `enable_font_subsetting`을 `true`로 설정한다. PDF에 실제 사용된 문자의 글리프만 포함하여 용량을 대폭 줄인다.
|
||||
|
||||
```php
|
||||
// config/dompdf.php
|
||||
'options' => [
|
||||
'enable_font_subsetting' => true, // ✅ 필수 — 사용 글자만 임베딩
|
||||
'enable_javascript' => false, // ✅ 권장 — PDF 내 JS 불필요
|
||||
// ...
|
||||
],
|
||||
```
|
||||
|
||||
| 설정 | 변경 전 | 변경 후 | 효과 |
|
||||
|------|---------|---------|------|
|
||||
| `enable_font_subsetting` | `false` | `true` | 폰트 전체(~4-5MB) → 사용 글자만(수십KB) |
|
||||
| `enable_javascript` | `true` | `false` | PDF 내 JS 코드 제거 |
|
||||
|
||||
> 한글 폰트는 11,172개의 완성형 글자를 포함하지만, 급여명세서에 사용되는 글자는 100~200자 수준이다. 서브셋팅으로 99% 이상의 불필요한 글리프를 제거한다.
|
||||
|
||||
### 5.3 경량화 체크리스트
|
||||
|
||||
- [ ] `config/dompdf.php`의 `enable_font_subsetting` → `true`
|
||||
- [ ] `enable_javascript` → `false` (PDF 내 JS 미사용 시)
|
||||
- [ ] Blade 뷰에 불필요한 이미지/외부 리소스 미포함
|
||||
- [ ] `font-weight`는 `normal`/`bold`만 사용 (미등록 weight가 fallback 폰트를 트리거하면 용량 증가)
|
||||
|
||||
---
|
||||
|
||||
## 6. 기존 코드 수정 가이드
|
||||
|
||||
구글 폰트를 사용하는 기존 PDF 뷰를 발견하면 다음 절차로 수정한다.
|
||||
|
||||
@@ -231,7 +280,7 @@ $pdf = Pdf::loadView('emails.payslip', ['payslipData' => $payslipData])
|
||||
|
||||
---
|
||||
|
||||
## 6. 긴급 복구 — 운영서버 권한 오류 발생 시
|
||||
## 7. 긴급 복구 — 운영서버 권한 오류 발생 시
|
||||
|
||||
이미 구글 폰트를 사용하는 코드가 배포되어 권한 오류가 발생한 경우의 즉시 조치이다. 근본 수정(구글 폰트 제거 + ensureKoreanFont 적용)을 반드시 병행한다.
|
||||
|
||||
@@ -246,7 +295,7 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/
|
||||
|
||||
---
|
||||
|
||||
## 7. 체크리스트
|
||||
## 8. 체크리스트
|
||||
|
||||
### PDF 뷰 작성 시
|
||||
|
||||
@@ -254,6 +303,7 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/
|
||||
- [ ] `<link href="https://fonts.googleapis.com/...">` 미포함
|
||||
- [ ] `font-family`에 `NanumGothic` 포함 (DomPDF 한글 지원)
|
||||
- [ ] `font-family` fallback에 `Malgun Gothic`, `sans-serif` 포함 (브라우저용)
|
||||
- [ ] `font-weight`는 `normal`/`bold`만 사용 (800 이상 금지)
|
||||
|
||||
### PDF 생성 코드 작성 시
|
||||
|
||||
@@ -279,6 +329,7 @@ sudo chmod -R 775 /home/webservice/mng/current/vendor/dompdf/dompdf/lib/fonts/
|
||||
|
||||
- 서버 운영 매뉴얼: `dev/deploys/ops-manual/README.md`
|
||||
- DomPDF 패키지: `barryvdh/laravel-dompdf` v3.1
|
||||
- DomPDF 설정: `mng/config/dompdf.php` — 서브셋팅, DPI 등
|
||||
- 구현 참조: `mng/app/Services/HR/PayrollService.php` — `ensureKoreanFont()`
|
||||
|
||||
---
|
||||
|
||||
Reference in New Issue
Block a user