728x90
728x90

App Services에 Next.js 15 배포하기 (VS Code, LocalGit)

들어가며

  • 애저(Azure) App Services에 Next.js 15 프로젝트를 배포 완료 후, 배포했던 과정을 정리해본다.
  • 포트 관련 문제로 여러번의 배포 실패 작업 후, 오랫동안 구글링을 통해 해결 방법을 찾아보다가 성공한 방법을 정리해본다.

 

방법

  • 우선, 내가 진행했던 프로젝트의 배포 환경은 다음과 같다.
    • Next.js v15.3.2
    • TailwindCSS, JavaScript, TypeScript
    • Node v20.19.1
  • 비주얼 스튜디오 코드(VS Code)Azure 확장을 이용하여 배포를 진행하였다. (LocalGit)
  • GitHub Actions을 이용하여 배포를 진행할 수도 있으나, 이 방법은 차후에 포스팅 해보려고 한다.

 

[1] 프로젝트 최상단 경로에 server.js 파일 생성하기

  • 프로젝트 최상단 경로(/)에 다음과 같이 server.js 파일을 생성해준다.
  • 애저(Azure) App Services에 홈페이지를 배포할 때, 기본적으로 8080 포트를 사용하기 때문에 반드시(!) 포트를 8080으로 설정해주어야 한다.

 

/sever.js
const { createServer } = require('http');
const { parse } = require('url');
const next = require('next');
const app = next({ dev: false });
const handle = app.getRequestHandler();
const port = process.env.PORT || 8080; // Azure가 사용하는 포트
app.prepare().then(() => {
createServer((req, res) => {
const parsedUrl = parse(req.url, true);
handle(req, res, parsedUrl);
}).listen(port, () => {
console.log(`> Ready on http://localhost:${port}`);
});
});

 

포트 설정을 제대로 해주지 않으면, 프로젝트를 Azure App Services에 배포하더라도 실행이 되지 않는 문제가 생길 수 있다.

 

[2] Next.js 설정 파일(next.config.js)에 standalone 설정 해주기

  • 프로젝트 최상단 경로(/)에 있는 Next.js 설정 파일(next.config.js 또는 next.config.ts) 파일에 다음과 같이 standalone 설정을 해준다.

 

/next.config.js (/next.config.ts)
import type { NextConfig } from 'next';
const nextConfig: NextConfig = {
output: 'standalone',
// ...
};
export default nextConfig;

 

output: 'standalone'은 앱을 독립 실행형으로 배포할 수 있도록 번들링 해주는 옵션이다. 이 옵션은 주로 Docker 배포나 서버 환경에 Node.js 앱을 최소 파일로 올릴 때 사용한다.

 

[3] package.json 파일 수정하기

  • 다음과 같이 start 명령을 실행할 때, 프로젝트 최상단 경로(/)에 있는 server.js 파일이 실행되도록 변경해준다.
  • 또한, Azure App Services에서 배포한 리소스의 버전과 일치하도록 Node.js 버전을 설정해준다.
    • Node LTS 20 : "node" : ">=20.0.0"
    • Node LTS 18 : "node" : ">=18.0.0"
    • 현재 프로젝트의 Node.js 버전에 맞게 Azure App Services에서 노드 버전을 설정해준다.
      • 현재 프로젝트의 Node.js 버전을 확인하려면 터미널에 node -v 명령을 실행한다.

 

/package.json
{
"name": "next-js",
"version": "0.1.0",
"private": true,
"scripts": {
"dev": "next dev --turbopack",
"build": "next build",
"start": "node server.js", // ✅
"lint": "next lint"
},
"engines": {
"node": ">=20.0.0" // ✅ Azure App Services 배포 버전
},
"dependencies": {
// ...
}
}

 

Azure 앱 서비스를 생성할 때, Node.js 버전을 선택해줄 수 있다. 이 버전에 맞게 package.json의 node 버전을 설정해준다.

 

[4] 빌드 작업 수행하기

  • 터미널에 아래 명령을 실행하여 빌드 작업을 수행해준다.
$ npm run build # 빌드

 

패키지 정리 후 빌드하기
  • 패키지 정리 후 깨끗하게 빌드 작업을 수행하고 싶다면, 빌드 작업 수행 전 다음과 같이 프로젝트 최상단 경로에 있는 node_modules 폴더와 package-lock.json 파일을 삭제한 후, 다시 패키지를 설치해준다.
  • 반드시 패키지들이 설치되어 있어야 빌드 작업을 수행할 수 있다.
$ rm -rf node_modules package-lock.json # 빌드 관련 파일 삭제
$ npm run install # 패키지 설치

 

[5] 배포 폴더 구성하기

deploy 폴더 생성 및 파일/폴더 복사해서 붙여넣기

  • 다음과 같이 프로젝트 최상단 경로(/)deploy 폴더를 생성해준다.
  • 그리고 다음과 같이 폴더와 파일을 구성해준다.
    • 빌드 후 생성된 .next 폴더 안의 standalone 폴더와 static 폴더
      • .next/standalone 폴더 안의 모든 내용들을 /deploy 경로에 복사해준다.
        • .next 폴더
        • package.json 파일
        • node_modules 폴더
        • server.js 파일 
      • .next/static 폴더 안의 모든 내용들을 /deploy/.next, /deploy/static 경로에 각각 복사해준다.
    • 프로젝트 최상단 경로(/)의 public 폴더를 /deploy 경로에 복사해준다.
📁 deploy (배포 루트)
├── .next/standalone/ ✅ (빌드 결과)
├── .next/static/ ✅ (빌드 결과)
├── public/ ✅ (정적 에셋 (이미지, 글꼴 등))
├── public/static/ ✅ (복사된 .next/static)
├── server.js ✅ (Next.js 실행 진입점) (포트 번호 8080 확인)
├── package.json
├── ...

 

 

server.js 파일 포트 번호 확인하기

  • /deploy/server.js 파일 안에서 currentPort의 값에 8080이 있는지 확인해 준다.
    • 만약 3000으로 되어있을 경우, 8080으로 수정해준다.

server.js 파일에서 포트 번호(currentPort) 확인 후 잘못되어 있을 경우 8080으로 수정해준다.

 

(참고) Next.js 프로젝트 빌드 전과 빌드 후의 프로젝트 구조
빌드 전 프로젝트 구조 빌드 후 프로젝트 구조
/my-next-app
├── pages/
├── public/
├── server.js
├── next.config.js
├── package.json
├── ...
/my-next-app
├── .next/
│   ├── standalone/       ⬅ 서버 실행에 필요한 모든 파일들
│   │   ├── server.js     ⬅ 이건 직접 만든 것과는 다름
│   │   ├── node_modules/
│   │   ├── package.json
│   │   ├── .next/
│   │   │   ├── ...
│   ├── standalone/         ⬅ 정적 리소스 (함께 복사 필요)
├── ...

 

빌드 작업 후, .next 폴더 안의 파일/폴더들

 

(참고) 명령어로 배포를 위해 필요한 파일/폴더 옮기기
# 1) deploy 디렉토리 초기화 및 생성
rm -rf deploy && mkdir -p deploy
# 2) /.next/standalone 안의 모든 파일/폴더들을 /deploy 경로로 복사
cp -r .next/standalone/. deploy/
# 3) public 폴더 복사 (이미지, 폰트 등 정적 자산)
cp -r public deploy/
# 4) /.next/static 폴더를 /deploy/.next 폴더 안으로 복사
mkdir -p deploy/.next
cp -r .next/static deploy/.next/
# 5) server.js 포트 번호 바꾸기 (3000 -> 8080)
sed -i 's/|| 3000/|| 8080/' deploy/server.js

 

[6] VS Code Azure 확장 설치 및 로그인하기

  • 비주얼 스튜디오 코드(VS Code)애저 확장(Azure Extensions)를 설치해준다.
    • Azure Tools
    • Azure App Service
 

Azure Tools - Visual Studio Marketplace

Extension for Visual Studio Code - Get web site hosting, SQL and MongoDB data, Docker Containers, Serverless Functions and more, all on Azure, all from VS Code, in this one extension from Microsoft.

marketplace.visualstudio.com

 

Azure App Service - Visual Studio Marketplace

Extension for Visual Studio Code - An Azure App Service management extension for Visual Studio Code.

marketplace.visualstudio.com

 

  • 위의 2가지 확장을 설치한 후, 다음과 같이 로그인을 해준다.
    • 명령 팔레트 실행하기 ([Ctrl/Cmd] + [Shift] + [P])
    • Azure: Sign In 클릭 후 로그인 작업 수행하기

명령 팔레트에서 애저 로그인 작업 수행하기

 

  • 다음과 같이 App Services 및 여러 정보가 표시되는지 확인한다.

 

[7] VS Code 설정하기 (배포 경로 설정하기)

  • 프로젝트 최상단 경로(/).vscode 폴더를 생성하고, 다음과 같이 settings.json 파일을 생성해주고 내용을 추가해준다.

 

.vscode/settings.json
  • 체크(✅) 표시된 부분만 본인의 경로에 맞게 추가해준다.
  • 이 설정은 배포 대상 폴더 경로를 지정해주는 설정이다.
{
"appService.zipIgnorePattern": ["node_modules{,/**}", ".vscode{,/**}"],
"appService.defaultWebAppToDeploy": "*************",
"appService.deploySubpath": "deploy", // ✅
"appService.showBuildDuringDeployPrompt": false
}

 

[8] Azure 포털에서 웹앱 생성하기

  • 애저 포털(https://portal.azure.com)App Services 페이지에서 웹앱(WebApp)을 다음과 같이 생성해준다.

 

웹앱 생성하기

  • App Services 서비스를 클릭한다.

App Services 페이지 진입

 

  • 자신이 배포하고자 하는 앱 타입에 맞게 설정해준다. 

[웹앱] 선택 (필요에 맞게 선택)

 

 

런타임 스택과 운영 체제 선택하기

  • 런타임 스택운영 체제를 잘 설정해줘야 한다.
    • 런타임 스택 : Next.js 프로젝트의 노드 버전
    • 운영 체제 : Linux

 

 

가격 책정 플랜 설정하기

  • 가격 책정 플랜포트폴리오 용도로는 B1 요금제가 적당하다고 한다.
    • 무료 플랜으로는 Next.js 프로젝트 배포가 힘들 수 있으니 최소 B1 요금제 부터 배포 하는데 문제가 없다고 한다.

 

환경 변수 설정하기

  • 웹앱 생성 후, Next.js 프로젝트에서 생성했던 환경 변수 파일(.env.local)의 내용들은 다음과 같이 [설정] > [환경 변수]@ 페이지에서 하나하나씩 등록을 해주어야 한다.

 

[9] VS Code에서 웹앱 배포하기

  • 이제 VS Code에서 웹앱 배포 작업을 수행해준다.
  • 다음과 같이 배포 관련 파일과 폴더들이 들어있는 deploy 폴더를 클릭한 후, [마우스 우클릭] > [Deploy to Web App...]을 클릭해준다.

 

  • 구독 정보배포 대상 웹앱 이름을 선택해준다.

 

배포를 하면 기존에 이미 웹에 배포된 내용들이 모두 지워진다. Deploy 버튼을 클릭해준다.

 

  • 터미널에서 배포가 성공적으로 되었는지 확인할 수 있다.

 

  • 배포가 완료되면, 배포된 페이지로 접속해서 실행이 되는지 확인해본다.
https://*****.azurewebsites.net

 

배포 작업이 실패할 경우

  • 웹앱 상세 페이지 하단의 [모니터링] 탭의 [로그 스트림]에서 로그를 확인해본 후, 디버깅 작업을 수행한다.

 

참고 사이트

 

자습서: Azure Static Web Apps에 하이브리드 Next.js 웹 사이트 배포

Azure Static Web Apps를 사용하여 Next.js 하이브리드 사이트를 생성하고 배포합니다.

learn.microsoft.com

 

Deploy Next.js to Azure: 3 Effective Strategies for Modern Developers

Are you considering using Azure to deploy your Next.js application, or looking for ways to leverage Azure’s robust features for your…

crayonconsulting.medium.com

 

728x90
728x90

App Services에 Next.js 15 배포하기 (VS Code, LocalGit)들어가며방법[1] 프로젝트 최상단 경로에 server.js 파일 생성하기[2] Next.js 설정 파일(next.config.js)에 standalone 설정 해주기[3] package.json 파일 수정하기[4] 빌드 작업 수행하기[5] 배포 폴더 구성하기deploy 폴더 생성 및 파일/폴더 복사해서 붙여넣기server.js 파일 포트 번호 확인하기[6] VS Code Azure 확장 설치 및 로그인하기[7] VS Code 설정하기 (배포 경로 설정하기)[8] Azure 포털에서 웹앱 생성하기웹앱 생성하기런타임 스택과 운영 체제 선택하기가격 책정 플랜 설정하기환경 변수 설정하기[9] VS Code에서 웹앱 배포하기배포 작업이 실패할 경우참고 사이트