[워드프레스] 16. 자원 : 워드프레스에서 CSS·JS 올바르게 불러오는 법

(워드프레스 해부 ⑯) 자원

CSS·JS를 붙일 때 헤더에 <link>나 <script>를 직접 박고 싶은 유혹이 든다. 워드프레스에선 이러면 안 된다. 대신 엔큐(enqueue) 시스템을 쓴다 — wp_enqueue_style(), wp_enqueue_script().

왜 굳이? 엔큐를 쓰면 워드프레스가 의존성·버전·중복을 알아서 관리한다. jQuery가 필요한 스크립트면 “jQuery 먼저 로드”를 자동 처리하고, 두 플러그인이 같은 라이브러리를 부르면 한 번만 로드한다. 직접 태그를 박으면 이 모든 게 깨진다.

직접 해보기

// functions.php — 내 스타일과 스크립트를 올바르게 등록
add_action( 'wp_enqueue_scripts', function() {
    wp_enqueue_style(
        'my-style',                          // 핸들(고유 이름)
        get_stylesheet_directory_uri() . '/my.css',
        array(),                             // 의존성
        '1.0'                                // 버전(캐시 무효화용)
    );
    wp_enqueue_script(
        'my-script',
        get_stylesheet_directory_uri() . '/my.js',
        array( 'jquery' ),                   // jQuery에 의존 → 먼저 로드됨
        '1.0',
        true                                 // 푸터에 로드(성능)
    );
} );

버전 인자가 은근히 중요하다. CSS를 고쳤는데 브라우저가 옛 버전을 캐시하고 있으면 반영이 안 되는데, 버전을 올리면 URL이 my.css?ver=1.1로 바뀌어 강제로 새로 받는다.

✅ 확인 — 스타일을 엔큐한 뒤 페이지 소스를 보면 <link ... id='my-style-css' href='.../my.css?ver=1.0'>처럼 핸들 이름이 붙은 태그가 뜬다. 워드프레스가 관리하는 방식으로 로드됐다는 증거다.

올바른 훅에서 등록하기

엔큐는 아무 데서나 하면 안 되고 정해진 훅에서 한다. 프런트는 wp_enqueue_scripts, 관리자 화면은 admin_enqueue_scripts, 블록 에디터는 enqueue_block_editor_assets. 훅을 맞춰야 그 화면에만 자원이 실린다.

add_action( 'wp_enqueue_scripts', function () {
    wp_enqueue_style( 'cozlab-main', get_stylesheet_uri(), array(), '1.0' );
    wp_enqueue_script(
        'cozlab-app',                         // 핸들(고유 이름)
        get_theme_file_uri( 'js/app.js' ),    // URL
        array( 'jquery' ),                    // 의존성 — jQuery 먼저
        '1.0',                                // 버전(캐시 무효화)
        true                                  //  앞에 로드
    );
} );

인자 뜯어보기 — 핸들·의존성·버전·푸터

인자	역할
핸들	고유 이름 — 중복 로드를 막는 열쇠
의존성	먼저 로드할 핸들 배열(예: [‘jquery’])
버전	캐시 무효화용 — 파일 바꾸면 올려야 새로 받음
푸터(true)	</body> 앞에 넣어 렌더 블로킹 완화

조건부 로드 — 필요한 데서만

성능의 핵심이다. 연락처 폼 스크립트를 모든 페이지에 싣지 말고, 그 페이지에서만 엔큐한다. is_page()·is_singular() 같은 조건 태그로 감싸면 된다. 안 쓰는 자원을 안 싣는 것만으로 사이트가 눈에 띄게 가벼워진다.

add_action( 'wp_enqueue_scripts', function () {
    if ( is_page( 'contact' ) ) {          // 연락처 페이지에서만
        wp_enqueue_script( 'contact-form', $url, array(), '1.0', true );
    }
} );

렌더 블로킹까지 — strategy와 스크립트 모듈

‘푸터에 넣기’가 전부이던 시절은 지났다. 요즘 워드프레스는 스크립트 로딩 전략을 표준 인자로 받는다 — 배열 형태의 5번째 인자에 strategy를 주면 defer·async 속성이 붙는다.

wp_enqueue_script( 'cozlab-app', $url, array(), '1.0',
    array( 'strategy' => 'defer', 'in_footer' => true ) );
// → <script defer src="..."> — HTML 파싱을 막지 않고 순서는 보장

// ES 모듈(import/export)을 쓴다면 — 전용 함수가 따로 있다
wp_enqueue_script_module( 'cozlab-widget',
    get_theme_file_uri( 'js/widget.js' ), array(), '1.0' );
// → <script type="module"> — 모듈은 원래 defer처럼 동작

고르는 기준: 다른 스크립트와 순서가 중요하면 defer(의존성 순서 보장), 완전히 독립적인 위젯이면 async. 그리고 새로 짜는 코드가 import를 쓴다면 wp_enqueue_script_module이 정석이다 — 일반 엔큐에 모듈 파일을 넣으면 import 구문에서 그대로 죽는다.

버전·설정값 넘기기 팁

파일이 바뀔 때마다 버전을 손으로 올리기 번거롭다면, 버전에 filemtime()(파일 수정 시각)을 넣으면 바뀔 때마다 캐시가 자동 갱신된다. 스크립트에 서버의 설정값(예: REST 주소·nonce)을 넘길 땐 wp_localize_script나 wp_add_inline_script로 붙인다. 그리고 jQuery는 코어에 이미 있으니 다시 로드하지 말고 의존성으로만 부른다.

wp_enqueue_script( 'cozlab-app', $url, array(), filemtime( $path ), true );
wp_add_inline_script( 'cozlab-app', 'const COZ = ' . wp_json_encode( array(
    'rest' => esc_url_raw( rest_url() ),
) ) . ';', 'before' );

엔큐를 제대로 쓰면 의존성·중복·캐시를 워드프레스가 알아서 관리해준다. 직접 태그를 박는 순간 이 모든 안전장치가 꺼진다는 걸 기억하자.

자원 로딩까지 봤으니, 다음 편은 wp-cron의 동작 원리와 예약 작업이다. 사실 워드프레스의 “크론”은 진짜 크론이 아니다.

자주 묻는 질문 (FAQ)

CSS·JS를 head에 직접 넣으면 안 되나요?

권장하지 않습니다. wp_enqueue_style·wp_enqueue_script를 쓰면 의존성·중복·순서를 워드프레스가 관리해 줍니다.

스크립트를 푸터에 넣으려면요?

wp_enqueue_script에서 in_footer를 true로 주면 됩니다. 렌더 블로킹을 줄일 수 있습니다.