渐进迁移页面路由至应用路由
盘点现有页面并逐路由迁移,调整数据获取与客户端边界,验证状态码、元数据和导航行为一致。
完整提示词
<context>
The two routers can run side by side in one app, so the migration is incremental: one route moves from `pages/` to `app/`, is checked, and the old file is deleted. The same URL must never exist in both. What breaks is rarely the JSX. It is the model change: components in `app/` are server components by default, so hooks, browser APIs and context providers need a `"use client"` boundary pushed as low as possible; `getServerSideProps`, `getStaticProps` and `getStaticPaths` become async server components, `generateStaticParams` and segment options; `next/head` becomes the Metadata API; `next/router` becomes `next/navigation` (`useRouter`, `usePathname`, `useSearchParams`), whose router has no `query` or `events`; `_app` and `_document` become the root layout. Caching and revalidation defaults have changed between major versions, so the target version's documentation decides them, not memory. Runtime CSS-in-JS libraries need extra setup in server components. API routes can stay in `pages/api` until there is a reason to move them to route handlers.
{{#next_version}}
Next.js version: {{next_version}}
{{/next_version}}
</context>
<task>
Migrate: {{scope}}
1. Inventory `pages/`: every route, its data-fetching method, dynamic segments, use of `next/router` (`query`, `events`, `asPath`), `next/head`, per-page layouts, and what `_app` and `_document` do (providers, global CSS, fonts, analytics, html attributes). Note middleware, `next.config` redirects and rewrites, and i18n config, since i18n routing works differently in `app/`.
2. Build the root layout in `app/` that reproduces `_app` and `_document`: html and body attributes, global CSS, fonts, and providers moved into one small client component.
3. Order the routes: static and simple pages first, then dynamic ones, then pages with auth, forms or heavy client state. Shared layouts move with their first route.
4. For each route, map: data fetching to an async server component or a client fetch with a reason; `getStaticPaths` to `generateStaticParams`; revalidation to the target version's segment options or fetch options; `notFound` and `redirect` returns to the `notFound()` and `redirect()` functions; `next/head` to `metadata` or `generateMetadata`; router usage to `next/navigation`. Mark the smallest component that needs `"use client"`.
5. Move one route, delete its `pages/` file in the same change, run the build and the tests, and load the route.
6. Check parity for that route: HTML output and status codes (200, 404, redirects), metadata and canonical tags, caching behaviour (fresh versus stale data), client navigation and scroll, and that no server-only secret ends up in a client component.
</task>
<constraints>
- Never leave the same path defined in both routers.
- Do not mark whole pages `"use client"` to make errors go away; explain any page that truly needs it.
- Do not state caching or revalidation defaults from memory; read them for the version in use and say which you assumed.
- Keep URLs, status codes and SEO output identical unless the user asks for a change.
{{> guardrails/verify-before-done}}
{{> guardrails/scope-discipline}}
</constraints>
<output_format>
## Inventory
Table: route | data fetching | router or head usage | risk (low, medium, high).
## Route order
Numbered list with the reason for each position.
## Per-route mapping
For each migrated route: old construct to new construct, and where the client boundary sits.
## Changes made
The diff summary per route, with build and test results.
## Parity check
Per route: status codes, metadata, caching and navigation, each pass or fail.
## Remaining routes
What is left, and any blocker (i18n, custom server, a library without server component support).
</output_format>可替换内容
- {{#next_version}}
- {{next_version}}
- {{/next_version}}
- {{scope}}
- {{> guardrails/verify-before-done}}
- {{> guardrails/scope-discipline}}
分类与标签
编程开发、前端框架迁移、路由改造、服务端组件、数据获取、兼容性验证