next.js

在开发模式下，Next.js Fast Refresh 会在每次保存时重新执行模块，因此顶层的 new DatabaseConnection(...)（或 postgres()、PrismaClient 等）每次都会创建一个新连接，直到 PostgreSQL 报错 remaining connection slots are reserved for non-replication superuser connections。解决方法是将客户端缓存在 globalThis 上，让连接在模块重新加载后依然保留：

import postgres from 'postgres';

declare module globalThis {
  let postgresSqlClient: ReturnType<typeof postgres> | undefined;
}

function connectOnceToDatabase() {
  if (!globalThis.postgresSqlClient) globalThis.postgresSqlClient = postgres();
  return globalThis.postgresSqlClient;
}

export const sql = connectOnceToDatabase();

同样的单例模式也适用于 Prisma（globalThis.prisma ??= new PrismaClient()）以及其他数据库驱动。此问题仅影响开发环境；生产构建不会按请求重新执行模块。

这是 Next.js 16.4.0 中由 #97664 引入的一个已知 Turbopack 开发模式回归问题。当页面 chunk 组复用 _app 的可用性数据时，页面模块可能会从客户端 chunk 中被省略，导致 SSR 成功但 hydration 失败，并报出 module factory is not available 错误。

永久修复方案：升级到包含 PR #98823 的 Next.js canary/preview 版本，该 PR 串联了 Pages Router 的开发客户端模块图。此修复已在 next@16.5.0-preview-358550b2-20261009 中验证通过。

npm install next@canary
rm -rf .next
npm run dev

如果无法升级，可以使用以下变通方案之一：

# 降级到最后一个未受影响的版本
npm install next@16.3.8
rm -rf .next
npm run dev

或者使用 webpack 而非 Turbopack 运行开发服务器：

npx next dev --webpack -p 3456

生产构建不受影响，因此在 16.4.0 上使用 next build && next start 也可以正常工作。

Next.js 16.4 默认启用 experimental.turbopackSharedRuntime。当 cacheComponents: true 时，Turbopack 会将其 chunk-group 引导脚本内联到预渲染的 shell 中，且不添加请求 nonce。诸如 script-src 'self' 'nonce-<random>' 的严格 CSP 会拦截该内联 <script id="_R_">，导致客户端运行时永远无法启动，hydration 失败。

解决方法：在 next.config.js 中禁用共享运行时：

module.exports = {
  experimental: {
    turbopackSharedRuntime: false,
  },
};

然后重新构建并重启：

next build && next start

这会恢复之前的行为，即引导脚本作为外部脚本加载，从而被 'self' 允许。该问题影响使用 Turbopack、React 19.2 且 cacheComponents: true 的 Next.js 16.4.0；使用脚本哈希并不实际，因为引导脚本会随路由和构建而变化。

将 Next.js 升级到 **16.4.0 或更高版本**，该版本中已修复此 Windows 符号链接问题：

pnpm add next@^16.4.0
# 或
yarn add next@^16.4.0

然后删除旧的构建输出并重新构建：

rm -r .next
pnpm build

现在，.next/standalone/node_modules 下生成的符号链接应解析到 .next/standalone/node_modules/.pnpm 内部，而不是指向构建机器的根目录 node_modules 或 Windows 绝对路径。该问题已在 Windows 上使用 pnpm 通过 Next.js 16.2.10 和 16.3.0 复现，并且有报告称使用 yarn 时也会出现类似的绝对路径符号链接行为。如果暂时无法升级，一个已报告的变通方法是在 Linux 上构建 standalone 输出，或在本地 Windows 容器构建中使用 webpack。

Next.js 在构建前会清空 distDir。当在 apps/web 中设置 distDir: "../../" 时,解析后的路径是 monorepo 根目录,因此 Next.js 会递归删除该目录。请确保 distDir 位于 Next.js 项目根目录内:

1. 编辑 apps/web/next.config.ts,移除不安全的设置或使用本地目录:

const nextConfig = {
  distDir: '.next',
}

2. 不要将 distDir 指向仓库根目录、用户主目录、/ 或其他项目。
3. 对于 Vercel monorepo 部署,进入 **Project Settings → General → Root Directory**,将其设置为 apps/web,而不是将 .next 移动到仓库根目录。这样 Vercel 会自动检测构建输出。
4. 在从 apps/web 构建之前,验证解析后的路径:

node -e "console.log(require('path').resolve('../../'))"

如果输出的是 monorepo 根目录或其他包含无关文件的目录,则该配置不安全。
5. 从 Next.js 16.3.5 升级到包含自定义 distDir 安全校验的更新版本。

删除是永久性的,不会经过系统回收站;请从 Git 或其他备份中恢复受影响的文件。