배포·자주 쓰는 기능

화면 다음으로 바로 붙는 기능과, 서버에 올리는 순서입니다.

제목과 설명

페이지 파일에서 metadata 객체를 내보내면 <title>과 설명 메타 태그가 됩니다. 레이아웃의 제목을 페이지가 덮어 씁니다.

export const metadata = {
  title: '글 목록',
  description: '최근 글을 모았습니다.'
}

export default function Page() {
  return <h1>글 목록</h1>
}

글마다 제목이 다르면 generateMetadata 함수에서 params를 await한 뒤 제목을 돌려줍니다. metadata는 서버에서만 실행되므로 클라이언트 컴포넌트 파일에는 두지 않습니다.

아이콘·OG 이미지는 파일 이름으로도 둘 수 있습니다. app/icon.png, app/opengraph-image.png처럼 두면 그 구간 메타데이터에 연결됩니다.

이미지

next/image의 Image는 크기를 맞추고, 최신 형식으로 줄이며, 화면 밖에 있을 때 늦게 불러옵니다. alt는 정보 이미지에 필수입니다. 장식이면 alt=""로 비웁니다.

import Image from 'next/image'

export default function Page() {
  return (
    <Image
      src="/hero.png"
      alt="책상 위 노트북"
      width={800}
      height={400}
    />
  )
}

src가 /hero.png이면 파일은 public/hero.png입니다. 다른 사이트의 이미지 주소는 설정에서 그 도메인을 허용해야 합니다. 키 이름과 옵션은 공식 문서의 Image Optimization을 봅니다. 너비·높이를 모르면 fill과 부모의 position: relative를 함께 씁니다.

UI가 없는 API

app/api/posts/route.js는 페이지가 아니라 HTTP 엔드포인트입니다. 주소는 /api/posts입니다. 함수 이름이 메서드입니다.

export async function GET() {
  return Response.json({ ok: true })
}

브라우저 화면이 필요 없고, 다른 프로그램이 JSON을 받아야 할 때 씁니다. 폼 저장은 보통 서버 함수로 충분하고, Route Handler는 웹훅·외부 앱·모바일처럼 HTTP가 경계일 때 맞습니다.

요청 앞단, Proxy

모든 페이지에 들어가기 전에 주소를 바꾸거나 헤더를 고치려면 프로젝트 루트(또는 src/)에 proxy.js를 둡니다. app과 같은 높이입니다. 파일은 프로젝트당 하나이고, 함수 이름은 proxy입니다.

import { NextResponse } from 'next/server'

export function proxy(request) {
  return NextResponse.redirect(new URL('/home', request.url))
}

export const config = {
  matcher: '/about/:path*'
}

matcher에 적힌 경로에서만 실행됩니다. Next.js 16 전에 배운 middleware.js와 같은 역할입니다. 세션 조회처럼 느린 일은 넣지 않습니다.

빌드하고 올리기

로컬에서 npm run build가 끝날 때까지 오류를 고칩니다.
npm start로 프로덕션 모드를 한 번 봅니다.
서버에 Node.js 20.9 이상을 두고, 빌드 결과와 node_modules(또는 서버에서 다시 npm ci 후 build)로 npm start를 실행합니다.

Vercel에 저장소를 연결하면 빌드와 서버 실행을 대신합니다. 서버 함수, proxy.js, 요청마다 그리는 페이지가 있으면 정적 파일만 푸는 호스팅으로는 부족합니다.

next.config에 output: 'export'를 두면 HTML 파일만 뽑습니다. 이 모드에서는 서버 함수, Proxy, 요청마다 바뀌는 렌더가 빠집니다. 소개 페이지만 있는 사이트에 맞습니다.

처음부터 HTML·CSS·JavaScript만 쓸 때는 Next.js를 만들지 않습니다. 브라우저에서 데이터베이스에 붙이고 파일을 올리는 절차는 정적 사이트에 있습니다.

환경 변수는 호스팅 설정에도 같은 이름으로 넣습니다. .env.local은 로컬 전용이라 서버에 자동으로 올라가지 않습니다.

옛 글과 다를 때

옛 자료	지금
`pages/index.js`, `getServerSideProps`	`app/.../page.js` 안에서 `await`
`useRouter().query`만으로 경로 값	페이지 인자의 `await params`
`fetch`는 기본 캐시	기본은 캐시하지 않음. 캐시가 필요하면 문서의 Caching, `use cache`
`middleware.js`의 `middleware` 함수	`proxy.js`의 `proxy` 함수 (Next.js 16)
`<img>`만 사용	가능하지만, 크기·용량은 `next/image`가 맡음