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
명령을 실행한다.
- 현재 프로젝트의 Node.js 버전을 확인하려면 터미널에
- Node LTS 20 :
/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": { // ... } }

[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
으로 수정해준다.
- 만약

(참고) 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/ ⬅ 정적 리소스 (함께 복사 필요) ├── ... |

(참고) 명령어로 배포를 위해 필요한 파일/폴더 옮기기
# 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 서비스를 클릭한다.

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

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

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

환경 변수 설정하기
- 웹앱 생성 후, Next.js 프로젝트에서 생성했던 환경 변수 파일(
.env.local
)의 내용들은 다음과 같이[설정] >
[환경 변수]@ 페이지에서 하나하나씩 등록을 해주어야 한다.
![]() |
![]() |
[9] VS Code에서 웹앱 배포하기
- 이제 VS Code에서 웹앱 배포 작업을 수행해준다.
- 다음과 같이 배포 관련 파일과 폴더들이 들어있는
deploy
폴더를 클릭한 후,[마우스 우클릭] > [Deploy to Web App...]
을 클릭해준다.

- 구독 정보와 배포 대상 웹앱 이름을 선택해준다.
![]() |
![]() |

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

- 배포가 완료되면, 배포된 페이지로 접속해서 실행이 되는지 확인해본다.
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
'DevOps > Azure' 카테고리의 다른 글
[Azure] Visual Studio 서비스를 이용하여 CRUD 애플리케이션 제작하기 (0) | 2023.06.07 |
---|---|
[Azure] Azure Machine Learning Service 사용해보기 : Notebooks (0) | 2023.06.01 |
[Azure] Azure Machine Learning Service 사용해보기 : Automated ML (0) | 2023.05.31 |
[Azure] Azure Machine Learning Service 사용해보기 : Designer (0) | 2023.05.31 |
[Azure] 쿠버네티스(Kubernetes) 실습하기 : AKS(Azure Kubernetes Service) 실습 (0) | 2023.05.30 |
[Azure] 쿠버네티스(Kubernetes) 실습하기 : 간단한 실습 해보기 (0) | 2023.05.29 |
[Azure] 쿠버네티스(Kubernetes) 실습하기 : 미니쿠베(minikube) 설치하기 (0) | 2023.05.27 |
[Azure] 도커(Docker) 실습하기 : 도커 이미지를 다른 사람과 공유하여 사용해보기 (0) | 2023.05.27 |