페이지 렌더 후 스크롤 적용

2026-07-06 11:55:58 +09:00
parent cb5cc68ecf
commit 6cb39603bf
9 changed files with 58 additions and 13 deletions
--- a/app/router.options.js
+++ b/app/router.options.js
@@ -3,7 +3,7 @@
 *
 * 기본 동작은 클라이언트 페이지 이동 중 이전 화면이 먼저 최상단으로
 * 이동하는 순간을 만들 수 있어, 실제 스크롤 처리는 클라이언트 플러그인에서
- * 라우트 전환 이후 새 화면 기준으로만 수행한다.
+ * Nuxt 페이지 렌더링 이후 새 화면 기준으로만 수행한다.
 */
 export default {
  /**
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -1,6 +1,6 @@
 # 배포 가이드

-> 로컬 기준 v1.10.44에서 `npm run lint`와 `npm run build` 검증을 통과했다. NAS 실제 컨테이너 기동과 도메인/프록시 접속 검증은 운영 배포 단계에서 진행한다.
+> 로컬 기준 v1.10.45에서 `npm run lint`와 `npm run build` 검증을 통과했다. NAS 실제 컨테이너 기동과 도메인/프록시 접속 검증은 운영 배포 단계에서 진행한다.

 ## 빌드 유형

--- a/docs/history.md
+++ b/docs/history.md
@@ -1,5 +1,11 @@
 # 의사결정 이력

+## 2026-07-06 v1.10.45 — 스크롤 적용은 라우트 확정이 아니라 페이지 렌더 완료를 기준으로 한다
+
+Vue Router의 `afterEach`는 URL과 라우트 상태가 바뀐 직후 실행되지만, Nuxt의 실제 페이지 컴포넌트 교체가 끝났다는 뜻은 아니다. 이 시점에 최상단 스크롤을 적용하면 이전 화면의 헤더 이미지가 먼저 보인 뒤 새 페이지가 붙을 수 있다. 따라서 `afterEach`에서는 이동 정보를 저장만 하고, Nuxt `page:finish` 이후 렌더 프레임을 기다린 뒤 새 화면 기준으로 스크롤을 적용한다.
+
+기본 `scrollBehavior: false`는 유지한다. 스크롤 제어 주체를 하나로 유지하면서 적용 시점만 늦춰, 이전 화면을 움직이지 않고 새 화면의 시작 위치를 정리하는 쪽을 선택했다.
+
 ## 2026-07-06 v1.10.44 — 스크롤은 라우트 전환 후 새 화면에서만 적용한다

 게시물 상세를 즉시 전환 방식으로 바꿔도 Vue Router 기본 스크롤 처리가 남아 있으면, 새 화면이 그려지기 전에 이전 화면이 먼저 최상단으로 이동하는 순간이 보일 수 있다. 사용자는 이를 페이지가 넘어가기 전에 화면이 깜빡이는 현상으로 느끼므로, 라우터 기본 `scrollBehavior`를 끄고 클라이언트 플러그인에서 라우트 확정 후 렌더 프레임을 기다린 다음 새 화면 기준으로만 스크롤을 적용한다.
--- a/docs/map.md
+++ b/docs/map.md
@@ -363,7 +363,7 @@
 | plugins/site-analytics.client.js | 공개 라우트 pageview·heartbeat·read 클라이언트 전송 |
 | plugins/bfcache-page-restore.client.js | 뒤로가기 캐시(bfcache) 복원 시 라우터 경로와 실제 URL 어긋남을 감지해 새로고침(HTML 문서 모드 페이지 이동 후 뒤로가기 잔상 방지) |
 | plugins/navigation-lock.client.js | 페이지 이동 중 `html.site-navigating` 클래스로 링크·버튼 클릭을 잠가 중복 클릭 차단(안전 타임아웃 포함) |
-| plugins/site-route-scroll.client.js | 라우트 전환 완료 후 새 화면에서 최상단·해시 위치 스크롤 적용(이동 전 이전 화면 스크롤 튐 방지) |
+| plugins/site-route-scroll.client.js | 라우트 변경 정보를 저장한 뒤 Nuxt `page:finish` 이후 새 화면에서 최상단·해시 위치 스크롤 적용(이동 전 이전 화면 스크롤 튐 방지) |

 ## 데이터베이스

--- a/docs/spec.md
+++ b/docs/spec.md
@@ -144,7 +144,7 @@
 ### 공개 URL 구조

 - `/posts` - 게시물 전체 목록. 사이트 설정 POST 설정의 `postListPageSize` 값 기준으로 서버 페이지네이션을 사용하며, 페이지 번호가 바뀌면 화면을 상단으로 이동한다. 하단 페이지네이션은 이전·다음 화살표와 페이지 번호 직접 이동을 함께 제공하며, 전체 페이지가 많으면 첫 페이지·끝 페이지·현재 페이지 주변 번호를 유지하고 중간 구간은 `...`으로 접는다.
- `/post/:slug` - 개별 게시물 상세. 직접 접속·SSR은 본문을 먼저 조회해 SEO 메타를 완성하고, 클라이언트 내부 이동은 새 상세 화면으로 즉시 전환한 뒤 데이터 준비 전에는 제목·메타·이미지·본문 자리 스켈레톤을 표시한다. 이동 중에는 `NuxtLoadingIndicator` 상단 진행바와 중복 클릭 잠금으로 피드백을 제공한다. Vue Router 기본 스크롤 처리는 끄고 라우트 전환 후 새 화면 기준으로 최상단 또는 해시 위치를 적용해 이동 전 이전 화면이 먼저 위로 튀지 않게 한다. 이전·다음 글은 상세 API 응답의 `previous`·`next`로 표시하며, `previous`는 더 과거 글, `next`는 더 최신 글을 뜻한다.
+- `/post/:slug` - 개별 게시물 상세. 직접 접속·SSR은 본문을 먼저 조회해 SEO 메타를 완성하고, 클라이언트 내부 이동은 새 상세 화면으로 즉시 전환한 뒤 데이터 준비 전에는 제목·메타·이미지·본문 자리 스켈레톤을 표시한다. 이동 중에는 `NuxtLoadingIndicator` 상단 진행바와 중복 클릭 잠금으로 피드백을 제공한다. Vue Router 기본 스크롤 처리는 끄고 Nuxt 페이지 렌더링 완료 후 새 화면 기준으로 최상단 또는 해시 위치를 적용해 이동 전 이전 화면이 먼저 위로 튀지 않게 한다. 이전·다음 글은 상세 API 응답의 `previous`·`next`로 표시하며, `previous`는 더 과거 글, `next`는 더 최신 글을 뜻한다.
 - `/` - 홈. 클라이언트 복귀 시에도 주요 데이터를 블로킹 조회한 뒤 전환한다.
 - `/sitemap.xml` - 공개 sitemap XML. 홈, 게시물 목록, 태그 목록, 공개 발행글, 공개 고정 페이지, 글이 있는 태그 URL을 요청 시점 DB 기준으로 자동 생성한다. 멤버십·비공개·초안·예약 대기 글과 `noindex` 글은 포함하지 않는다.
 - `/robots.txt` - 크롤러 안내 파일. 관리자·API·회원 설정·로그인 경로를 제외하고 `Sitemap: /sitemap.xml` 절대 URL을 제공한다.
--- a/docs/update.md
+++ b/docs/update.md
@@ -1,5 +1,11 @@
 # 업데이트 이력

+## v1.10.45
+
+- 페이지 이동 스크롤 적용 시점을 `router.afterEach` 직후에서 Nuxt `page:finish` 이후로 변경.
+- 이전 화면이 먼저 최상단으로 이동하며 헤더 이미지가 잠깐 보이던 현상을 추가 완화.
+- 라우트 변경 시점에는 스크롤 요청만 저장하고 새 페이지 렌더링 완료 뒤 한 번만 적용하도록 정리.
+
 ## v1.10.44

 - Vue Router 기본 스크롤 이동을 비활성화해 페이지 이동 전 이전 화면이 먼저 최상단으로 튀는 현상 완화.
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
 {
  "name": "sori.studio",
-  "version": "1.10.44",
+  "version": "1.10.45",
  "lockfileVersion": 3,
  "requires": true,
  "packages": {
    "": {
      "name": "sori.studio",
-      "version": "1.10.44",
+      "version": "1.10.45",
      "hasInstallScript": true,
      "dependencies": {
        "@nuxtjs/tailwindcss": "^6.14.0",
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
  "name": "sori.studio",
-  "version": "1.10.44",
+  "version": "1.10.45",
  "private": true,
  "type": "module",
  "imports": {
--- a/plugins/site-route-scroll.client.js
+++ b/plugins/site-route-scroll.client.js
@@ -2,12 +2,16 @@
 * 공개 라우트 이동 후 새 화면 기준으로 스크롤 위치를 정리한다.
 *
 * Vue Router 기본 scrollBehavior는 전환 중 이전 화면을 먼저 움직일 수 있어
- * `app/router.options.js`에서 끄고, 여기서는 라우트가 확정된 뒤 프레임을
- * 기다렸다가 새 화면에서만 최상단 또는 해시 위치로 이동한다.
+ * `app/router.options.js`에서 끄고, 여기서는 Nuxt 페이지 렌더링이 끝난 뒤
+ * 새 화면에서만 최상단 또는 해시 위치로 이동한다.
 */
 export default defineNuxtPlugin((nuxtApp) => {
  const router = nuxtApp.$router

+  /** @type {{ id: number, to: import('vue-router').RouteLocationNormalizedLoaded, from: import('vue-router').RouteLocationNormalizedLoaded } | null} */
+  let pendingRouteScroll = null
+  let routeScrollId = 0
+
  /**
   * 브라우저 렌더 프레임을 기다린다.
   * @returns {Promise<void>} 프레임 대기 Promise
@@ -19,18 +23,45 @@ export default defineNuxtPlugin((nuxtApp) => {
  })

  /**
-   * 이동 완료 후 스크롤 위치를 적용한다.
+   * 이동 완료 후 적용할 스크롤 정보를 저장한다.
   * @param {import('vue-router').RouteLocationNormalizedLoaded} to - 이동 대상 라우트
   * @param {import('vue-router').RouteLocationNormalizedLoaded} from - 이전 라우트
-   * @returns {Promise<void>}
+   * @returns {void}
   */
-  const applyRouteScroll = async (to, from) => {
+  const queueRouteScroll = (to, from) => {
    if (to.fullPath === from.fullPath) {
      return
    }

+    routeScrollId += 1
+    pendingRouteScroll = {
+      id: routeScrollId,
+      to,
+      from
+    }
+  }
+
+  /**
+   * 새 페이지 렌더링 이후 스크롤 위치를 적용한다.
+   * @returns {Promise<void>}
+   */
+  const applyPendingRouteScroll = async () => {
+    const routeScroll = pendingRouteScroll
+
+    if (!routeScroll) {
+      return
+    }
+
    await waitForFrame()

+    if (!pendingRouteScroll || pendingRouteScroll.id !== routeScroll.id) {
+      return
+    }
+
+    pendingRouteScroll = null
+
+    const { to } = routeScroll
+
    if (to.hash) {
      const targetId = decodeURIComponent(to.hash.slice(1))
      const target = document.getElementById(targetId)
@@ -49,6 +80,8 @@ export default defineNuxtPlugin((nuxtApp) => {
  }

  router.afterEach((to, from) => {
-    applyRouteScroll(to, from)
+    queueRouteScroll(to, from)
  })
+
+  nuxtApp.hook('page:finish', applyPendingRouteScroll)
 })