[Nuxt Content] Nuxt Icon 오류 해결과 Custom Collection 기반 오프라인 아이콘 구성

🔍 1. 현상 및 근본 원인 분석

네트워크 아웃바운드 통신이 제한되거나 **SSL 복호화 장비(자체 서명 인증서 주입)**가 개입하는 특수 네트워크 환경에서, Nuxt 개발 서버 구동 중 터미널 콘솔에 대량의 아이콘 페치 실패 경고(failed to load icon)가 지속적으로 발생하는 현상이 나타난다.

🚨 에러 로그 형태

WARN  [Icon] failed to load icon lucide:search
WARN  [Icon] failed to load icon simple-icons:nuxt
WARN  [Icon] failed to load icon fluent-emoji-flat:light-bulb

💡 발생 메커니즘

@nuxt/icon 모듈은 기본적으로 온디맨드(On-Demand) 방식의 원격 조회를 시도한다. 화면 렌더링 시점에 외부 오픈소스 아이콘 API 서버(https://api.iconify.design)로 실시간 요청을 날리는데, 이때 런타임 환경에 따라 이중적인 결과가 발생한다.

• 브라우저(Client) 단: 로컬 PC 브라우저 검증망을 통과하여 인터넷 릴레이 통신이 성공하므로 화면에는 아이콘이 정상 출력된다.
• Node.js 서버(SSR) 단: Nuxt 내부 서버 엔진(Nitro/Vite) 레이어에서는 보안 장비가 주입한 자체 서명 인증서 체인을 신뢰할 수 없거나 아웃바운드가 막혀 통신을 거부(fetch failed)한다. 결과적으로 화면에는 뜨지만 서버 터미널에는 에러 폭탄이 찍히는 괴리가 발생한다.

🛠️ 2. 아키텍처적 해결 방안 (Full Localizing & Layer Merge)

보안 정책을 우회하기 위해 프로젝트 구동 방식을 외부 의존성이 전무한 완전한 오프라인 로컬(Standalone) 모드로 전환한다. 특히 brolog 프로젝트와 같이 Nuxt 멀티 레이어(extends) 아키텍처를 사용하는 경우, 설정 파일 간의 병합(Merge) 특성을 고려하여 명확한 타겟팅 설정을 적용해야 한다.

① 1단계: 메인 프로젝트 루트에 오프라인 패키지 설치

원격 API 서버를 찌르지 않도록 현재 감지된 모든 아이콘 컬렉션을 개발 의존성(devDependencies)으로 로컬에 다운로드한다. 명령어는 반드시 brolog 프로젝트의 메인 루트 디렉토리에서 실행해야 한다.

npm i -D @iconify-json/lucide @iconify-json/simple-icons @iconify-json/fluent-emoji-flat @iconify-json/logos @iconify-json/mdi @iconify-json/skill-icons @iconify-json/unjs @iconify-json/streamline-plump @iconify-json/icon-park-solid @iconify-json/emojione

📦 리소스 오버헤드 검증: 아이콘 팩을 로컬에 받아도 실제 용량은 수 MB 수준으로 미비하다. 빌드 시점에는 **트리쉐이킹(Tree-shaking)**이 엄격하게 작동하여 코드 상에서 실제 호출한 아이콘(SVG 데이터)만 최종 프로덕션 번들에 인라인 주입되므로 전체 런타임 성능과 빌드 용량 최적화에 훨씬 유리하다.

② 2단계: 하위 레이어 설정 조정 (layer/nuxt.config.ts)

하위 레이어 설정 내부에 원격 조회를 강제하는 provider: 'iconify' 속성이 남아있으면 메인 설정과 충돌을 일으킨다. 이를 내부 엔진 우선 방식으로 변경하고 로컬 번들 가이드를 주입한다.

// layer/nuxt.config.ts
export default defineNuxtConfig({
  icon: {
    customCollections: [
      {
        prefix: 'custom',
        dir: resolve('./app/assets/icons'),
      },
    ],
    clientBundle: {
      scan: true,
      includeCustomCollections: true,
    },
    // ⚠️ 원격 API를 강제 조회하는 기존 'iconify'를 주석처리하여 로컬 우선 유도
    //provider: 'iconify', 
    serverBundle: 'local',
    fallbackToApi: false
  },
})

③ 3단계: 메인 서비스 설정 덮어쓰기 (docs/nuxt.config.ts)

상속받은 하위 레이어 설정을 메인 컨텍스트에서 최종 확정 지으며 외부 통신 폴백을 완벽히 차단한다.

// docs/nuxt.config.ts
export default defineNuxtConfig({
  extends: [
    '../layer' // 하위 레이어 상속 경로
  ],

  icon: {
    // 멀티 레이어 병합 시에도 외부 통신을 차단하도록 고정 쐐기 선언
    serverBundle: 'local', // 1단계에서 설치한 node_modules 리소스 강제 매핑
    fallbackToApi: false   // 어떠한 상황에서도 외부 원격 API 서버 조회를 금지
  }
})

📊 3. 최적화 적용 결과 비교