Vite. 빌드 시 파라미터 기반 소스 코드 문자열 치환

1. 개요

Vite 빌드 실행 시 전달한 환경변수를 사용하여 기존 소스 코드의 특정 문자열을 치환한다.

문자열 치환에는 @rollup/plugin-replace를 사용하며, 각 치환 규칙마다 대상 소스 파일을 명시적으로 지정하여 의도하지 않은 치환을 방지한다.

핵심 요구사항

• 기존 소스 코드를 수정하지 않는다.
• 빌드 시 전달한 파라미터로 상수 값을 변경한다.
• 여러 상수를 동시에 치환할 수 있다.
• 각 치환 규칙은 지정된 소스 파일에만 적용한다.
• 파라미터가 없으면 해당 치환 플러그인을 등록하지 않는다.
• 문자열 치환을 다른 일반 변환 플러그인보다 먼저 수행한다.
• 별도의 빌드 스크립트 없이 vite.config.js에서 처리한다.
• 개발 서버에서는 문자열 치환을 적용하지 않는다.

적용 기술

기능	사용 방법
빌드 파라미터 전달	환경변수 (process.env)
문자열 치환	@rollup/plugin-replace
대상 파일 지정	include
조건부 치환	plugins 동적 구성
실행 순서	enforce: 'pre'
빌드 시에만 적용	apply: 'build'

2. 패키지 설치

npm install -D @rollup/plugin-replace

Vite는 호환되는 Rollup 플러그인을 사용할 수 있으며, 플러그인 적용 순서와 빌드 전용 실행을 지원한다.

Vite

3. 소스 코드 구성

다음과 같은 프로젝트 구조를 가정한다.

project/
├── src/
│   ├── index.js
│   ├── a.js
│   └── b.js
├── vite.config.js
├── index.html
└── package.json

src/a.js

const a = 1;

console.log(a);

src/b.js

const b = 2;

console.log(b);

두 소스 파일은 기존 코드 그대로 유지한다. 빌드 시점에만 각 파일의 지정된 상수 값을 치환한다.

src/index.js에서 두 파일을 import한다고 가정한다.

import './a.js';
import './b.js';

4. Vite 설정

vite.config.js

import { defineConfig } from 'vite';
import replace from '@rollup/plugin-replace';
import { resolve } from 'node:path';

const { a, b } = process.env;

const replaceFile = (file, search, value) => ({
  ...replace({
    include: resolve(file),
    values: { [search]: value },
    delimiters: ['', ''],
    preventAssignment: true,
  }),
  enforce: 'pre',
  apply: 'build',
});

export default defineConfig({
  plugins: [
    ...(a !== undefined ? [
      replaceFile('src/a.js', 'const a = 1;', `const a = ${a};`),
    ] : []),

    ...(b !== undefined ? [
      replaceFile('src/b.js', 'const b = 2;', `const b = ${b};`),
    ] : []),
  ],
});

4.1. 대상 파일 제한

include: resolve(file)

각 치환 플러그인은 명시적으로 지정한 파일에만 적용된다.

예를 들어 src/a.js에 대한 치환 규칙은 다른 파일에 같은 문자열이 존재하더라도 해당 파일을 변경하지 않는다.

4.2. 문자열 치환 설정

values: {
  [search]: value,
},
delimiters: ['', ''],
preventAssignment: true,

• values: 검색할 문자열과 치환할 문자열을 지정한다.
• delimiters: ['', '']: 기본 식별자 경계 제한을 제거하여 지정한 문자열을 그대로 검색한다.
• preventAssignment: true: 플러그인의 할당 표현식 관련 안전 옵션을 활성화한다.

@rollup/plugin-replace는 이러한 문자열 치환 옵션과 파일 필터링을 지원한다.

npm+1

4.3. 조건부 플러그인 등록

...(a !== undefined ? [
  replaceFile('src/a.js', 'const a = 1;', `const a = ${a};`),
] : [])

환경변수 a가 존재할 때만 해당 치환 플러그인을 등록한다.

환경변수가 없으면 빈 배열이 반환되므로 플러그인이 등록되지 않는다.

4.4. 플러그인 실행 순서

enforce: 'pre'

Vite의 일반 변환 플러그인보다 먼저 문자열 치환을 수행한다.

원본 코드의 문자열을 기준으로 치환하기 때문에 가능한 한 변환 이전에 처리하는 것이 적합하다.

4.5. 빌드 시에만 적용

apply: 'build'

문자열 치환을 프로덕션 빌드에만 적용한다.

따라서 vite 개발 서버를 실행할 때는 치환 플러그인이 동작하지 않는다.

enforce와 apply는 Vite에서 공식적으로 지원하는 플러그인 속성이다.

Vite

5. 빌드 실행

5.1. package.json

{
  "scripts": {
    "dev": "vite",
    "build": "vite build"
  }
}

별도의 빌드 스크립트를 작성할 필요가 없다.

5.2. 모든 상수 변경

a=11 b=22 npm run build

빌드 과정에서 다음과 같이 치환된다.

src/a.js

const a = 11;

console.log(a);

src/b.js

const b = 22;

console.log(b);

5.3. 일부 상수만 변경

a=11 npm run build

파일	처리 결과
src/a.js	const a = 11;
src/b.js	const b = 2; (변경 없음)

환경변수 b가 없으므로 b.js에 대한 문자열 치환 플러그인은 등록되지 않는다.

5.4. 파라미터 없이 빌드

npm run build

• 두 문자열 치환 플러그인 모두 등록되지 않는다.
• 기존 소스 코드의 값이 그대로 사용된다.
• 일반적인 Vite 빌드가 실행된다.

위 환경변수 지정 구문은 macOS 및 Linux 셸 기준이다. Windows에서는 PowerShell의 환경변수 설정 구문이나 cross-env를 사용할 수 있다.

6. 동일 파일에서 여러 상수를 치환하는 경우

여러 상수가 하나의 파일에 존재한다면 values에 여러 치환 규칙을 전달할 수 있다.

예를 들어 src/config.js에 다음 코드가 있다고 가정한다.

const a = 1;
const b = 2;

이 경우에는 다음과 같이 구성할 수 있다.

const values = {
  ...(a !== undefined ? {
    'const a = 1;': `const a = ${a};`,
  } : {}),

  ...(b !== undefined ? {
    'const b = 2;': `const b = ${b};`,
  } : {}),
};

export default defineConfig({
  plugins: [
    ...(Object.keys(values).length > 0 ? [{
      ...replace({
        include: resolve('src/config.js'),
        values,
        delimiters: ['', ''],
        preventAssignment: true,
      }),
      enforce: 'pre',
      apply: 'build',
    }] : []),
  ],
});

이 방식은 동일 파일에 여러 치환 대상이 존재하는 경우에 적합하다.

각 환경변수가 없으면 해당 치환 규칙만 제외되며, 모든 환경변수가 없으면 플러그인 자체가 등록되지 않는다.

7. 주의사항

7.1. 정확한 문자열 일치

@rollup/plugin-replace는 JavaScript 구문을 분석하는 것이 아니라 문자열을 검색하여 치환한다.

예를 들어 다음 설정은:

values: {
  'const a = 1;': 'const a = 11;',
}

아래 코드에는 일치하지 않는다.

const a=1;

따라서 원본 소스 코드의 공백이나 선언 형태가 변경되면 치환되지 않을 수 있다.

7.2. 치환 대상이 없어도 빌드가 성공할 수 있음

지정한 파일에 검색 문자열이 존재하지 않더라도 기본적으로 오류가 발생하지 않는다.

따라서 치환 성공 여부가 중요한 빌드에서는 별도의 검증이 필요할 수 있다.

7.3. 환경변수의 자료형

환경변수는 문자열로 전달된다.

예를 들어:

a=11 npm run build

process.env.a의 값은 숫자 11이 아니라 문자열 "11"이다.

숫자 상수를 치환하는 경우 실제 값이 유효한 숫자 형식인지 검증하는 것이 좋다.

문자열 상수를 치환한다면 다음과 같이 JSON.stringify()를 사용한다.

replaceFile(
  'src/config.js',
  "const name = 'old';",
  `const name = ${JSON.stringify(process.env.name)};`
)

7.4. 원본 파일 유지

문자열 치환은 Vite의 빌드 과정에서 수행된다.

따라서 실제 소스 파일의 내용은 변경되지 않으며, 치환된 코드가 번들링 과정에 전달된다.

최종 번들에서는 코드 압축이나 최적화로 인해 소스 코드 형태가 달라질 수 있다.

7.5. 빌드 대상 파일만 처리

플러그인은 Vite가 모듈로 처리하는 파일에 적용된다.

include로 특정 파일을 지정했더라도 해당 파일이 빌드의 의존성 그래프에 포함되지 않으면 치환이 수행되지 않는다.

또한 public 디렉터리에서 그대로 복사되는 정적 파일은 이 방식의 변환 대상이 아니다.

7.6. 환경변수 전달 시 유의사항

process.env는 Vite 설정 파일을 실행하는 Node.js 프로세스에서 읽는다.

a, b처럼 일반적인 이름은 기존 시스템 환경변수와 충돌할 가능성이 있으므로, 실제 프로젝트에서는 BUILD_A, BUILD_B처럼 구별되는 이름을 사용하는 것도 좋다.

환경변수로 전달한 값이 최종 번들에 포함될 수 있으므로 비밀번호나 비밀키를 전달해서는 안 된다.

8. 최종 권장 구성

항목	권장 방식
빌드 명령	npm run build
파라미터 전달	a=11 b=22 npm run build
문자열 치환	@rollup/plugin-replace
대상 범위	파일별 include 지정
서로 다른 파일	파일별 플러그인 등록
동일 파일의 다중 치환	values에 여러 규칙 등록
파라미터 누락	해당 플러그인 또는 치환 규칙 제외
실행 순서	enforce: 'pre'
개발 서버 제외	apply: 'build'
원본 코드 수정	하지 않음
별도 빌드 스크립트	필요 없음

9. 결론

Vite 환경에서 빌드 파라미터에 따라 기존 소스 코드의 문자열을 치환하려면, @rollup/plugin-replace와 vite.config.js의 조건부 플러그인 구성을 사용하는 방식이 적합하다.

이 방식의 주요 장점은 다음과 같다.

• 기존 소스 코드를 변경하지 않는다.
• 빌드 명령에서 환경변수로 치환값을 전달할 수 있다.
• 대상 파일을 명시하여 의도하지 않은 치환을 줄일 수 있다.
• 여러 상수를 독립적으로 관리할 수 있다.
• 파라미터가 없는 경우 불필요한 플러그인을 등록하지 않는다.
• 별도의 빌드 스크립트 없이 기존 Vite 프로젝트에 적용할 수 있다.

단, 문자열의 정확한 일치를 전제로 하므로 치환 대상 파일과 원본 문자열이 명확하게 정해져 있고, 해당 코드의 형식이 안정적으로 유지되는 프로젝트에 사용하는 것이 적합하다.