# 常见问题 (/docs/reference/faq)

关于 Better Auth 的常见问题。



此页面包含有关 Better Auth 的常见问题、常见问题及其他有用信息。

<Accordions>
  <Accordion id="auth-client-not-working" title="认证客户端无法正常工作">
    当遇到 `createAuthClient` 相关错误时，请确保使用正确的导入路径，因为其会根据环境而有所不同。

    如果你在 React 前端使用认证客户端，你需要从 `/react` 导入它：

    ```ts title="component.ts"
    import { createAuthClient } from "better-auth/react";
    ```

    而如果你在 Next.js 中间件、服务器操作、服务器组件或任何与服务器相关的地方使用认证客户端，你可能需要从 `/client` 导入它：

    ```ts title="server.ts"
    import { createAuthClient } from "better-auth/client";
    ```
  </Accordion>

  <Accordion id="getsession-not-working" title="getSession 无法正常工作">
    如果尝试在服务器环境（例如 Next.js 服务器组件）中调用 `authClient.getSession`，它是无法工作的，因为它无法访问 Cookie。你可以使用 `auth.api.getSession` 并传入请求头。

    ```tsx title="server.tsx"
    import { auth } from "./auth";
    import { headers } from "next/headers";

    const session = await auth.api.getSession({
        headers: await headers()
    })
    ```

    如果你需要出于其他目的在服务器上使用认证客户端，你仍然可以传入请求头：

    ```tsx title="server.tsx"
    import { authClient } from "./auth-client";
    import { headers } from "next/headers";

    const session = await authClient.getSession({
        fetchOptions:{
          headers: await headers()
        }
    })
    ```
  </Accordion>

  <Accordion id="corporate-proxy-configuration" title="如何配置企业代理以用于服务器端请求">
    如果你需要为 Better Auth 的出站请求（例如 OAuth 提供商请求）配置企业代理，可以使用 undici 的 ProxyAgent 来设置全局的 fetch 代理。

    ```typescript title="auth.ts"
    import { betterAuth } from "better-auth";
    import { ProxyAgent, setGlobalDispatcher } from "undici";

    const proxyAgent = new ProxyAgent("http://your-proxy.example.com:8080");
    setGlobalDispatcher(proxyAgent);

    export const auth = betterAuth({
      // 你的配置
    });
    ```

    由于 Better Auth 在服务器端运行，你可以通过 undici 的全局调度器完全控制 Node.js 的 fetch 行为。这种方法可以让 Better Auth 的所有出站请求都通过你的企业代理。

    <Callout type="info">
      了解更多关于 undici ProxyAgent 的信息，请参考 [undici 文档](https://github.com/nodejs/undici/blob/main/docs/docs/api/ProxyAgent.md)。
    </Callout>
  </Accordion>

  <Accordion id="adding-custom-fields-to-the-users-table" title="向用户表添加自定义字段">
    Better Auth 提供了一种类型安全的方式来扩展用户和会话模式，请查看我们关于<Link href="/docs/concepts/database#扩展核心架构">扩展核心模式</Link>的文档。
  </Accordion>

  <Accordion id="difference-between-getsession-and-usesession" title="getSession 与 useSession 的区别">
    `useSession` 和 `getSession` 实例在使用方式上存在根本区别，具体取决于场景。

    `useSession` 是一个 Hook，这意味着每当会话数据发生变化时，它都可以触发重新渲染。

    如果你有需要根据用户或会话数据来改变的 UI，你可以使用这个 Hook。

    <Callout type="warn">
      出于性能考虑，不要在 `layout.tsx` 文件中使用此 Hook。
      我们建议使用 RSC，并通过服务器认证实例使用 `auth.api.getSession` 来获取会话数据。
    </Callout>

    `getSession` 返回一个包含数据和错误的 Promise。

    在你不应该使用 `useSession` 的其他所有情况下，都应该使用 `getSession`。

    <Callout type="info">
      `getSession` 在服务器和客户端认证实例上都可用。
      不仅仅是在后者。
    </Callout>
  </Accordion>

  <Accordion id="common-typescript-errors" title="常见的 TypeScript 错误">
    如果你遇到 TypeScript 错误，请确保你的 tsconfig 中将 `strict` 设置为 `true`：

    ```json title="tsconfig.json"
    {
      "compilerOptions": {
        "strict": true,
      }
    }
    ```

    如果无法将 strict 设置为 true，可以启用 `strictNullChecks`：

    ```json title="tsconfig.json"
    {
      "compilerOptions": {
        "strictNullChecks": true,
      }
    }
    ```

    你可以在我们的 <Link href="/docs/concepts/typescript#typescript-配置">TypeScript 文档</Link> 中了解更多信息。
  </Accordion>

  <Accordion id="can-i-remove-name-image-or-email-fields-from-the-user-table" title="我可以从用户表中移除 `name`、`image` 或 `email` 字段吗？">
    目前，你无法从用户表中移除 `name`、`image` 或 `email` 字段。

    我们计划在未来对此提供更多的自定义灵活性，但目前你还无法移除这些字段。
  </Accordion>

  <Accordion id="dual-module-hazard-issue" title="双模块风险问题">
    如果你遇到类似如下的错误：

    ```
    No request state found. Please make sure you are calling this function within a `runWithRequestState` callback.
    ```

    这通常是由**双模块风险**引起的——当 `better-auth` 或 `@better-auth/core` 的多个版本存在于你的依赖树中时。这在升级到 v1.4+ 后很常见，尤其是在 Cloudflare Workers、Nuxt 或使用 `oauthProvider` 插件时。

    ### 如何诊断 [#如何诊断]

    检查你是否安装了重复的 Better Auth 包：

    ```bash
    # 对于 pnpm 用户
    pnpm why @better-auth/core
    pnpm why better-auth

    # 对于 npm 用户
    npm ls @better-auth/core
    npm ls better-auth

    # 对于 yarn 用户
    yarn why @better-auth/core
    yarn why better-auth
    ```

    如果看到列出了多个版本，说明存在双模块风险。

    ### 如何修复 [#如何修复]

    #### 基本步骤 [#基本步骤]

    首先确保依赖关系干净，并且所有 Better Auth 包都使用兼容的版本。

    <Callout type="tip">
      **重新干净安装：**

      ```bash
      # 移除 node_modules 和锁文件
      rm -rf node_modules
      rm pnpm-lock.yaml # 或 package-lock.json 或 yarn.lock

      # 重新安装依赖
      pnpm install # 或 npm install 或 yarn install
      ```

      检查你的 `package.json`，确保所有与 Better Auth 相关的包（`better-auth`、`@better-auth/core`、`@better-auth/oauth-provider` 等）都使用兼容的版本。
    </Callout>

    #### 包管理器解析问题 [#包管理器解析问题]

    如果你使用的是 Yarn v1（Classic）或 pnpm v9，可能需要强制 `better-call` 解析为单个实例。

    <Callout type="warn">
      **对于 Yarn v1 / pnpm v9 用户：**

      手动安装 `better-call` 并将其同时添加到 `dependencies` 和 `resolutions` 中，以强制它提升到顶层：

      ```json title="package.json"
      {
        "dependencies": {
          "better-call": "^1.1.8",
          // ... 其他依赖
        },
        "resolutions": {
          "better-call": "^1.1.8"
        }
      }
      ```

      然后重新安装依赖：

      ```bash
      yarn install # 或 pnpm install
      ```

      注意：Yarn v3 和 pnpm v10 通常不会出现此问题。
    </Callout>

    <Callout type="error">
      **重要：** 确保将 `better-auth` 和相关包安装到 `dependencies`，而不是 `devDependencies`。
    </Callout>

    #### 打包器解析问题 [#打包器解析问题]

    这是一个打包器层面的问题，其中同一模块被解析为不同的实例。目标是让打包器将模块解析为同一实例。

    <Callout type="info">
      **对于 Next.js 用户：**

      在 `next.config.js` 中将 `better-auth` 添加到 `serverExternalPackages`：

      ```ts title="next.config.js"
      const config = {
        serverExternalPackages: ['better-auth']
      };
      ```
    </Callout>

    <Callout type="info">
      **对于 Cloudflare Workers 用户：**

      确保在 `wrangler.toml` 中启用了 `nodejs_compat` 兼容标志：

      ```toml title="wrangler.toml"
      compatibility_flags = ["nodejs_compat"]
      ```
    </Callout>

    #### 验证修复 [#验证修复]

    运行诊断命令以确认每个包只存在一个版本：

    ```bash
    pnpm why @better-auth/core
    pnpm why better-auth
    pnpm why better-call
    ```

    你应该看到每个包只列出一个版本。

    <Callout type="info">
      相关问题：[#6613](https://github.com/better-auth/better-auth/issues/6613)、[yjs#438](https://github.com/yjs/yjs/issues/438)
    </Callout>
  </Accordion>
</Accordions>