Nuxt 4 集成 GitHub 登录：从原理到实践（开发 + 生产环境完整版）

sequenceDiagram
participant 用户 as 用户 (浏览器)
participant 前端 as 应用前端 (Nuxt)
participant 后端 as 应用后端 (Nuxt Server)
participant GitHubAuth as GitHub 授权服务器
participant GitHubAPI as GitHub 资源服务器
用户->>前端: 1. 点击“GitHub登录”
前端->>后端: 2. 跳转到 /api/auth/github
后端->>GitHubAuth: 3. 302重定向到 GitHub (带 client_id, redirect_uri, state)
GitHubAuth-->>用户: 4. 显示授权页面
用户->>GitHubAuth: 5. 登录GitHub账号并点击“Authorize”
GitHubAuth->>后端: 6. 302重定向回调地址 (带授权码 & state)
后端->>GitHubAuth: 7. 用授权码 + client_secret 请求 Access Token
GitHubAuth-->>后端: 8. 返回 Access Token
后端->>GitHubAPI: 9. 用 Access Token 请求用户信息 (GET /user)
GitHubAPI-->>后端: 10. 返回用户数据 (id, login, avatar_url...)
后端->>后端: 11. 用 session 密码加密用户数据，存入 Cookie
后端->>用户: 12. 302重定向回首页 (附带加密 Cookie)
用户->>前端: 13. 访问首页，浏览器自动携带 Cookie
前端->>后端: 14. Vue组件通过 useUserSession() 请求 /api/_auth/session
后端->>后端: 15. 解密 Cookie，验证身份
后端-->>前端: 16. 返回用户数据
前端-->>用户: 17. 页面显示“欢迎，用户名”

npx nuxi@latest module add auth-utils

export default defineNuxtConfig({
  modules: ["nuxt-auth-utils"],
  runtimeConfig: {
    oauth: {
      github: {
        clientId: "", // 留空，由环境变量注入
        clientSecret: "",
      },
    },
  },
});

export default defineOAuthGitHubEventHandler({
  // 使用模块内置的 GitHub OAuth 处理器
  async onSuccess(event, { user }) {
    await setUserSession(event, {
      user: {
        githubId: String(user.id),
        login: user.login,
        name: user.name,
        avatarUrl: user.avatar_url,
        email: user.email, // 注意：可能为 null
      },
      loggedInAt: Date.now(),
    });

    // 重定向回首页（或来源页）
    return sendRedirect(event, "/");
  },
  onError(event, error) {
    console.error("GitHub OAuth error:", error);
    return sendRedirect(event, "/?auth_error=true");
  },
});

<script setup>
const { loggedIn, user, clear } = useUserSession();
const loginWithGitHub = () => {
  // 跳转到 GitHub 授权页
  navigateTo("/api/auth/github", { external: true });
};
</script>
<template>
  <div>
    <div v-if="loggedIn">
      <img :src="user.avatarUrl" class="w-8 h-8 rounded-full" />
      <span>{{ user.name || user.login }}</span>
      <button @click="clear">登出</button>
    </div>
    <button v-else @click="loginWithGitHub">GitHub 登录</button>
  </div>
</template>

pnpm dev

// server/api/store-redirect.post.ts
export default defineEventHandler(async (event) => {
  const { redirect } = await readBody(event);

  // 校验 redirect 是否为内部路径（防止开放重定向）
  if (!redirect || typeof redirect !== "string" || !redirect.startsWith("/")) {
    return { ok: false };
  }

  await setUserSession(event, { redirect });
  return { ok: true };
});

import { parseURL } from "ufo";

const { redirect } = await readBody(event);

// 解析路径，确保是内部路径
const parsed = parseURL(redirect);
if (!redirect || !parsed.pathname || parsed.host) {
  return { ok: false };
}

<script setup>
const { loggedIn } = useUserSession();
const route = useRoute();

const loginWithGitHub = async () => {
  // 将当前完整路径保存到 session
  await $fetch("/api/store-redirect", {
    method: "POST",
    body: { redirect: route.fullPath },
  });
  navigateTo("/api/auth/github", { external: true });
};
</script>

// server/api/auth/github.get.ts
export default defineOAuthGitHubEventHandler({
  async onSuccess(event, { user }) {
    // 获取之前存储的来源页
    const session = await getUserSession(event);
    let redirect = (session.redirect as string) || "/";

    // 清理 session 中的 redirect（避免下次重复使用）
    await setUserSession(event, { ...session, redirect: undefined });

    // 存入用户信息
    await setUserSession(event, {
      user: {
        githubId: String(user.id),
        login: user.login,
        name: user.name,
        avatarUrl: user.avatar_url,
        email: user.email,
      },
      loggedInAt: Date.now(),
    });

    // 重定向回来源页
    return sendRedirect(event, redirect);
  },

  async onError(event, error) {
    console.error("GitHub OAuth error:", error);
    return sendRedirect(event, "/login?error=true");
  },
});

用户从 /en/docs/123 点击登录

登录成功后若重定向到 /（默认语言首页）

服务器渲染的是中文 HTML，但 URL 是 /，而客户端期望的是英文内容

导致水合警告：Hydration completed but contains mismatches

用户从 /en/docs/123 来，登录后回到 /en/docs/123

服务器根据 URL 中的 /en 前缀渲染对应的语言版本

客户端 hydration 时，DOM 结构与 URL 完全匹配，水合警告自然消失

# 编辑 /etc/profile 或 ~/.bashrc，添加：
export NUXT_SESSION_PASSWORD=your-production-32-char-password
export NUXT_OAUTH_GITHUB_CLIENT_ID=your_prod_client_id
export NUXT_OAUTH_GITHUB_CLIENT_SECRET=your_prod_client_secret
# 使环境变量生效
source ~/.bashrc

module.exports = {
  apps: [
    {
      name: "moongate",
      script: "./server/index.mjs",
      instances: 1,
      exec_mode: "fork",
      env: {
        NODE_ENV: "production",
        NUXT_PUBLIC_SITE_URL: "https://moongate.top",
        PORT: 3000,
        HOST: "0.0.0.0",
        // 引用系统环境变量（更安全）
        NUXT_SESSION_PASSWORD: "your-production-32-char-password",
        NUXT_OAUTH_GITHUB_CLIENT_ID: "your_prod_client_id",
        NUXT_OAUTH_GITHUB_CLIENT_SECRET: "your_prod_client_secret",
      },
    },
  ],
};

name: Deploy To Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 24
          cache: pnpm

      - name: Install dependencies
        run: pnpm install

      - name: Build
        run: pnpm build

      - name: Deploy via Rsync
        uses: burnett01/rsync-deployments@7.0.1
        with:
          switches: -avz --delete
          path: .output/
          remote_path: /var/www/my-site/
          remote_host: ${{ secrets.SERVER_HOST }}
          remote_user: ${{ secrets.SERVER_USER }}
          remote_key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Start service via SSH
        uses: appleboy/ssh-action@v1.0.0
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          envs: NUXT_SESSION_PASSWORD, NUXT_OAUTH_GITHUB_CLIENT_ID, NUXT_OAUTH_GITHUB_CLIENT_SECRET
          script: |
            cd /var/www/my-site

            cat > ecosystem.config.js << EOF
            module.exports = {
              apps: [{
                name: "moongate",
                script: "./server/index.mjs",
                instances: 1,
                exec_mode: "fork",
                env: {
                  NODE_ENV: "production",
                  NUXT_PUBLIC_SITE_URL: "https://moongate.top",
                  PORT: 3000,
                  HOST: "0.0.0.0",
                  NUXT_SESSION_PASSWORD: "$(echo -n "$NUXT_SESSION_PASSWORD")",
                  NUXT_OAUTH_GITHUB_CLIENT_ID: "$(echo -n "$NUXT_OAUTH_GITHUB_CLIENT_ID")",
                  NUXT_OAUTH_GITHUB_CLIENT_SECRET: "$(echo -n "$NUXT_OAUTH_GITHUB_CLIENT_SECRET")"
                }
              }]
            }
            EOF

            pm2 restart ecosystem.config.js --update-env