RuoYi-Vue와 같이 프론트엔드(Vue.js)와 백엔드(Spring Boot)가 분리된 프로젝트를 운영하다 보면, 관리 편의성을 위해 이를 하나의 JAR 파일로 통합하여 배포해야 할 때가 있습니다. 이 가이드에서는 RuoYi-Vue의 두 아키텍처를 하나로 병합하는 구체적인 절차를 다룹니다.

1. 백엔드 서비스 설정 변경

먼저 Spring Boot 백엔드에서 정적 리소스를 처리하고 화면을 렌더링할 수 있도록 설정해야 합니다.

의존성 추가

ruoyi-admin 모듈의 pom.xml 파일에 Thymeleaf 템플릿 엔진 의존성을 추가합니다.

<!-- Thymeleaf 템플릿 엔진 -->
<dependency>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-thymeleaf</artifactId>
</dependency>

애플리케이션 설정

application.yml 파일에서 Thymeleaf가 프론트엔드 빌드 결과물을 참조할 수 있도록 경로를 설정합니다.

spring:
  thymeleaf:
    prefix: classpath:/dist/
    mode: HTML
    encoding: utf-8
    cache: false

정적 리소스 및 뷰 컨트롤러 구성

ruoyi-framework 모듈의 ResourcesConfig.java 파일을 수정하여 프론트엔드 정적 파일의 경로를 매핑합니다.

import org.springframework.core.Ordered;
import org.springframework.web.servlet.config.annotation.ViewControllerRegistry;

@Override
public void addResourceHandlers(ResourceHandlerRegistry registry) {
    /* 기존 설정 유지 */
    // 빌드된 정적 리소스 경로 매핑
    registry.addResourceHandler("/static/**").addResourceLocations("classpath:/dist/static/");
}

@Override
public void addViewControllers(ViewControllerRegistry registry) {
    // 인덱스 페이지 설정 및 우선순위 부여
    registry.addViewController("/").setViewName("index.html");
    registry.addViewController("/index").setViewName("index.html");
    registry.setOrder(Ordered.HIGHEST_PRECEDENCE);
}

보안 설정 업데이트

SecurityConfig.java에서 프론트엔드 자원들에 대해 인증 없이 접근할 수 있도록 권한을 개방합니다.

.antMatchers(
    HttpMethod.GET,
    "/",
    "/index",
    "/*.html",
    "/**/*.html",
    "/**/*.css",
    "/**/*.js",
    "/static/**"
).permitAll()

2. 프론트엔드 프로젝트 수정

단일 서버 환경에 맞춰 Vue.js 프로젝트의 라우팅과 API 주소 설정을 변경해야 합니다.

라우터 모드 변경

ruoyi-ui/src/router/index.js에서 브라우저의 새로고침 시 404 오류를 방지하기 위해 mode를 hash로 변경합니다.

export default new Router({
  mode: 'hash', // history에서 hash로 변경
  scrollBehavior: () => ({ y: 0 }),
  routes: constantRoutes
})

API 주소 설정

프론트엔드와 백엔드가 동일한 포트를 사용하므로 .env.production 파일의 API 베이스 경로를 비워둡니다.

# 프로덕션 환경 API 경로
VUE_APP_BASE_API = ''

의존성 패키지 보정

package.json 파일에서 core-js 버전에 ^ 기호를 추가하여 호환성을 확보한 뒤 라이브러리를 다시 설치합니다.

"core-js": "^3.x.x", // 기존 버전 앞에 ^ 추가

이후 터미널에서 npm install 명령어를 실행합니다.

3. 빌드 및 배포 과정

모든 설정이 완료되면 프론트엔드를 빌드하고 백엔드에 통합합니다.

1. 프론트엔드 디렉토리에서 npm run build:prod를 실행합니다.
2. 생성된 dist 폴더의 모든 내용을 백엔드 프로젝트의 ruoyi-admin/src/main/resources/dist 경로로 복사합니다.
3. Maven을 사용하여 백엔드 프로젝트를 패키징합니다.

이제 백엔드 서버를 구동하면 추가적인 프론트엔드 서버(Nginx 등) 없이도 지정된 포트를 통해 시스템에 바로 접속할 수 있습니다.