GitHub OAuth2 登录写成“登录地狱”？90%开发者都踩过的坑，我替你填平了！

你是不是也遇到过这种场景：

• 前端点击“用 GitHub 登录”，跳转到 GitHub 授权页；
• 用户授权成功，GitHub 重定向回你的回调地址 /auth/github/callback；
• 你拿到 code，去换 token，返回了 401 Unauthorized；
• 你检查了 client_id、client_secret、redirect_uri，一个字符都没错；
• 你甚至把代码拷到 Postman 里跑，居然能成功；
• 但一回到 Spring Boot 项目，就死活不行——你怀疑人生了。

别慌。这不是你的错。这是 Spring Boot + OAuth2 + 前后端分离 的“经典三重暴击”。

今天，我就带你一层层扒开这层皮，看清楚：为什么你的 OAuth2 登录，总在最后一步“掉线”？

---

原理深挖：OAuth2 流程中，谁在“偷走”你的请求？

我们先画一张清晰的流程图，看清每一步谁在“管事”：

你以为问题出在“后端没拿到 code”？错！

真正的致命陷阱，藏在第 6 步：OAuth2LoginAuthenticationFilter 的执行环境。

Spring Security 的 OAuth2LoginAuthenticationFilter 是一个服务器端过滤器，它默认只处理服务器重定向（server-side redirect），而不处理前端发起的 AJAX 请求。

当你在前后端分离架构中，前端用 window.location.href = '/auth/github' 跳转，没问题——这是浏览器行为，符合 OAuth2 的“授权码模式”。

但！当用户授权完成，GitHub 重定向回 /auth/github/callback?code=xxx 时，这个请求是浏览器发起的，Spring Security 能处理。

那问题出在哪？

问题出在：你试图用前端 JS 去“手动”调用 /auth/github/callback，或者你用了 Axios 去“模拟”这个回调流程。

---

九大坑点代码实录：从“我以为”到“我错了”

❌ 坑1：前端用 Axios 请求 /auth/github/callback，以为能“模拟”回调

// 前端错误代码（React 示例）
const handleGithubLogin = async () => {
  const code = new URLSearchParams(window.location.search).get('code');
  const res = await axios.get('/auth/github/callback', {
    params: { code } // ❌ 错误！这不是 API 调用！
  });
  localStorage.setItem('token', res.data.token); // 永远拿不到 token
};

你以为你在“调用接口”，实际上你在“冒充 GitHub”发请求。

Spring Security 的 OAuth2LoginAuthenticationFilter 不是 REST API！它是一个过滤器，依赖于完整的 HTTP 重定向上下文，包括：

• Referer 头（用于校验 redirect_uri）
• Cookie 会话状态（用于绑定 state 参数）
• 未被拦截的原始请求流

你用 Axios 发一个 GET 请求，连 Referer 都是你的前端域名，GitHub 根本不会信任你。

🚨 结果：401 Unauthorized，或 invalid_request，或直接 500。

✅ 正确做法：让浏览器自己完成重定向，后端只负责“收尾”

// 后端配置：Spring Security OAuth2Login 配置（正确姿势）
@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
        http
            .csrf(csrf -> csrf.disable()) // 前后端分离，禁用 CSRF
            .authorizeHttpRequests(auth -> auth
                .requestMatchers("/auth/github/callback").permitAll() // 允许回调
                .anyRequest().authenticated()
            )
            .oauth2Login(oauth2 -> oauth2
                .loginPage("/auth/github") // 自定义登录入口（可选）
                .userInfoEndpoint(userInfo -> userInfo
                    .userService(customOAuth2UserService()) // 自定义用户加载
                )
                .successHandler((request, response, authentication) -> {
                    // ✅ 这里才是“登录成功”的终点
                    String jwt = jwtService.generateToken(authentication);
                    response.sendRedirect("http://localhost:5173/login-success?token=" + jwt); // 重定向回前端
                })
                .failureHandler((request, response, exception) -> {
                    response.sendRedirect("http://localhost:5173/login-failed?error=" + exception.getMessage());
                })
            );
        return http.build();
    }

    @Bean
    public OAuth2UserService<OAuth2UserRequest, OAuth2User> customOAuth2UserService() {
        return userRequest -> {
            OAuth2User oAuth2User = new DefaultOAuth2User(
                List.of(new SimpleGrantedAuthority("ROLE_USER")),
                userRequest.getUserInfo().getAttributes(),
                "sub"
            );
            return oAuth2User;
        };
    }
}

✅ 关键点：不要让前端“调用”回调接口，而是让浏览器完成整个 OAuth2 重定向流程，后端在 successHandler 中生成 JWT，重定向回前端页面。

❌ 坑2：忘记配置 redirect-uri 与 GitHub App 设置不一致

# application.yml（错误写法）
spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: your-client-id
            client-secret: your-secret
            redirect-uri: "{baseUrl}/auth/github/callback" # ❌ 用 {baseUrl} 在前后端分离中可能失效！

问题在哪？

{baseUrl} 是 Spring Security 的占位符，它会自动解析为 http://localhost:8080。

但你的前端跑在 http://localhost:5173，GitHub 重定向时，会把 redirect_uri 传为 http://localhost:5173/auth/github/callback。

而你后端配置的是 http://localhost:8080/auth/github/callback → 不匹配！

🚨 结果：GitHub 返回 redirect_uri_mismatch

✅ 正确做法：显式写死重定向 URI（前后端分离必须如此）

# application.yml（正确写法）
spring:
  security:
    oauth2:
      client:
        registration:
          github:
            client-id: your-client-id
            client-secret: your-secret
            redirect-uri: "http://localhost:8080/auth/github/callback" # ✅ 显式写死
        provider:
          github:
            authorization-uri: https://github.com/login/oauth/authorize
            token-uri: https://github.com/login/oauth/access_token
            user-info-uri: https://api.github.com/user
            user-name-attribute: id

同时，在 GitHub Developer Settings 中，也必须配置相同的 Authorization callback URL：

http://localhost:8080/auth/github/callback

⚠️ 注意：前端页面的 URL 不需要出现在 GitHub 配置中！ 只需要后端的回调地址。

❌ 坑3：使用 @RestController + @GetMapping("/auth/github/callback") 手动处理 code

@RestController
public class GithubAuthController {

    @GetMapping("/auth/github/callback")
    public ResponseEntity<?> handleCallback(@RequestParam String code) {
        // ❌ 自己去调用 GitHub API 换 token？别干这蠢事！
        RestTemplate restTemplate = new RestTemplate();
        String tokenUrl = "https://github.com/login/oauth/access_token";
        HttpHeaders headers = new HttpHeaders();
        headers.setContentType(MediaType.APPLICATION_JSON);
        String body = String.format(
            "{\"client_id\":\"%s\",\"client_secret\":\"%s\",\"code\":\"%s\"}",
            clientId, clientSecret, code
        );
        ResponseEntity<Map> response = restTemplate.postForEntity(tokenUrl, body, Map.class);
        // ... 拿到 token，再拉取用户信息，再生成 JWT
        // 你这不是在用 OAuth2，你是在用 HTTP 客户端写一个山寨版 OAuth2
        return ResponseEntity.ok(response.getBody());
    }
}

你以为你“更灵活”？

你失去了：

• Spring Security 自动管理的 state 防止 CSRF
• 自动的 redirect_uri 校验
• 自动的 token 缓存与刷新机制
• 与 OAuth2UserService 的无缝集成
• 最重要的：你绕过了 Spring Security 的认证上下文！

🚨 结果：你手动拼的 token 没有权限，用户信息无法绑定到 SecurityContext，后续接口依然 403。

✅ 正确做法：完全交给 Spring Security 管理，只自定义用户加载逻辑

@Component
public class CustomOAuth2UserService implements OAuth2UserService<OAuth2UserRequest, OAuth2User> {

    @Autowired
    private UserRepository userRepository;

    @Override
    public OAuth2User loadUser(OAuth2UserRequest userRequest) throws OAuth2AuthenticationException {
        OAuth2User oAuth2User = new DefaultOAuth2User(
            Collections.singletonList(new SimpleGrantedAuthority("ROLE_USER")),
            userRequest.getUserInfo().getAttributes(),
            "id" // GitHub 的用户标识字段是 "id"
        );

        // ✅ 从数据库加载或创建用户
        String githubId = oAuth2User.getAttribute("id").toString();
        User user = userRepository.findByGithubId(githubId)
            .orElseGet(() -> {
                User newUser = new User();
                newUser.setGithubId(githubId);
                newUser.setName(oAuth2User.getAttribute("name").toString());
                newUser.setEmail(oAuth2User.getAttribute("email") != null ? oAuth2User.getAttribute("email").toString() : "");
                return userRepository.save(newUser);
            });

        // ✅ 把用户信息绑定到 OAuth2User，后续可通过 Authentication 获取
        return new CustomOAuth2User(user, oAuth2User.getAttributes());
    }
}

✅ 你不需要手动处理 code、token、user info。Spring Security 会自动完成。你只需要在 loadUser 中把 GitHub 用户映射到你的业务用户。

---

坑4：前端接收 JWT 后，没有正确存储和携带

// 前端错误：接收 token 后，没存，也没发
window.location.href = "/login-success?token=" + token; // ❌ 仅跳转，没存
// 后续请求依然没 Authorization 头

✅ 正确做法：前端接收 token，存入 localStorage，自动注入请求头

// 登录成功回调页（login-success.vue）
mounted() {
  const urlParams = new URLSearchParams(window.location.search);
  const token = urlParams.get('token');
  if (token) {
    localStorage.setItem('authToken', token);
    // 重定向到主页面，自动带上 token
    window.location.href = '/dashboard';
  }
}

// axios 拦截器
axios.interceptors.request.use(config => {
  const token = localStorage.getItem('authToken');
  if (token) {
    config.headers.Authorization = `Bearer ${token}`;
  }
  return config;
});

---

坑5：忘记配置 HttpSecurity 的 sessionManagement，导致会话冲突

// ❌ 缺少配置，可能在集群或无状态场景下崩溃
http.sessionManagement(session -> session.sessionCreationPolicy(SessionCreationPolicy.IF_REQUIRED));

✅ 正确做法：明确设为无状态

http
    .sessionManagement(session -> session
        .sessionCreationPolicy(SessionCreationPolicy.STATELESS) // ✅ 前后端分离必须！
    )

为什么？因为 OAuth2 登录完成后，你用的是 JWT，不是 HTTP Session。Spring 默认会创建 Session，导致内存泄漏、集群部署失败、Token 被忽略。

---

最终架构总结：前后端分离 OAuth2 登录黄金流程

graph TD
    A[前端点击“GitHub 登录”] --> B[前端跳转到 /auth/github]
    B --> C[后端返回 302 到 GitHub 授权页]
    C --> D[用户授权 GitHub]
    D --> E[GitHub 重定向回 /auth/github/callback?code=xxx]
    E --> F[Spring Security 自动处理：code → token → user info]
    F --> G[CustomOAuth2UserService 加载/创建用户]
    G --> H[成功：生成 JWT 并重定向到前端页面 /login-success?token=xxx]
    H --> I[前端存入 localStorage]
    I --> J[前端后续请求自动携带 Authorization: Bearer xxx]
    J --> K[后端用 JwtFilter 验证 token，建立 SecurityContext]

---

避坑指南：OAuth2 登录九字真言

不手动调回调，不手动换 token，不混用 session

1. 别用 Axios 请求 /auth/github/callback —— 它不是 API，是重定向终点。
2. redirect-uri 必须显式写死 —— {baseUrl} 在前后端分离中是陷阱。
3. 完全交给 Spring Security 管理 OAuth2 流程 —— 你只需要写 OAuth2UserService。
4. JWT 生成后，用 redirect 而非 return json —— 让浏览器完成状态切换。
5. Session 必须设为 STATELESS —— 否则你用的不是无状态架构。
6. GitHub App 的回调 URL 必须与后端配置完全一致 —— 包括协议（http/https）、端口、路径。
7. 前端接收 token 后，立即存入 localStorage，并自动注入请求头。
8. 测试时用 Chrome 无痕模式 —— 避免缓存和 Cookie 干扰。
9. 永远不要自己实现 OAuth2 客户端逻辑 —— Spring Security 已经做得比你强 10 倍。

---

你不是不会写代码，你是被“伪前后端分离”的伪架构骗了。

OAuth2 从来不是“调个接口”那么简单，它是一场浏览器、服务器、第三方平台之间的精密舞蹈。

你只要站对位置，让浏览器跳它的舞步，后端只负责接住、验证、发奖券（JWT），剩下的，Spring Security 会替你优雅地完成。

别再折腾了。
现在，关掉你那个写了 500 行的 OAuth2 手动实现代码，
删掉它。
然后，用上面的配置，重新跑一遍。

你会回来感谢我的。