Wasp 0.14 接入 GitHub 社交登录OAuth从零配置到数据定制【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/waspGitHub 认证GitHub Authentication是 Wasp 内置的社交登录方案之一无需手写 OAuth 回调逻辑即可开箱使用。本文以 Wasp 0.14 为例完整讲解如何在main.wasp与schema.prisma中启用 GitHub 登录、创建 GitHub OAuth App、配置GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET环境变量、生成登录页并通过configFn与userSignupFields覆盖默认行为、定制用户注册字段。读完本文你将能够在自己的 Wasp 应用中独立落地 GitHub 登录并理解其底层实现原理。为什么在 Wasp 里用 GitHub 登录Wasp 对 GitHub 认证提供了开箱即用的支持。当你的应用面向开发者群体时GitHub 是一个很好的外部认证选择——绝大多数开发者已经拥有 GitHub 账号让用户使用 GitHub 账号登录可以把注册流程简化到一键完成。本文会依次带你完成以下工作在 Wasp 文件中启用 GitHub 认证添加User实体创建 GitHub OAuth App添加必要的 Route 与 Page在页面中使用 Wasp 生成的 Auth UI 组件。设置 GitHub 认证的完整步骤启用 GitHub 认证由一系列步骤组成。完成后的main.wasp骨架大致如下完整的 Wasp 文件结构说明见 认证配置结构// Configuring the social authentication app myApp { auth: { ... } } // Defining routes and pages route LoginRoute { ... } page LoginPage { ... }步骤 1在 Wasp 文件中添加 GitHub Auth首先正确配置auth对象。在main.wasp中声明userEntity指向将要定义的User实体并在methods字典中加入gitHub: {}app myApp { wasp: { version: ^0.14.0 }, title: My App, auth: { // 1. 指定 User 实体下一步会定义它 userEntity: User, methods: { // 2. 启用 GitHub Auth gitHub: {} }, onAuthFailedRedirectTo: /login }, }TypeScript 项目中的写法完全一致Wasp 声明式配置与 JS/TS 语言无关。onAuthFailedRedirectTo用于指定认证失败时的重定向地址这里指向/login。步骤 2添加 User 实体接着在项目根目录的schema.prisma文件中定义app.auth.userEntity指向的实体// 3. 定义 user entity model User { id Int id default(autoincrement()) // Add your own fields below // ... }id字段是必需的其余字段如username、displayName、email等根据业务需求自行添加。步骤 3创建 GitHub OAuth App要使用 GitHub 作为认证方式需要先在 GitHub 创建 OAuth App并把 Client ID 与 Client Secret 提供给 Wasp登录 GitHub 账号访问https://github.com/settings/developers选择New OAuth App填写应用所需信息配置Authorization callback URL开发环境下填写http://localhost:3001/auth/github/callback当 API 服务器部署地址确定后可创建使用该地址的新应用例如https://your-server-url.com/auth/github/callback点击Register application在下一页点击Generate a new client secret复制 Client ID 和 Client secret下一步会用到。回调地址中的3001端口对应 Wasp 开发模式下 API 服务器的默认端口路径/auth/github/callback由 Wasp 生成的 OAuth 回调路由接管。步骤 4添加环境变量在项目根目录的.env.server文件中添加以下环境变量值取自上一步GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret这两个环境变量是强制性的从 Wasp 生成器的源码可以看到当 GitHub 认证启用后服务端环境变量校验要求GITHUB_CLIENT_ID与GITHUB_CLIENT_SECRET必须存在缺失时会抛出带明确提示的错误见 waspc/data/Generator/templates/sdk/wasp/server/env.ts 中isGitHubAuthEnabled分支。步骤 5添加必要的 Route 与 Page在main.wasp中定义认证所需的 Route 和 Page// ... route LoginRoute { path: /login, to: LoginPage } page LoginPage { component: import { Login } from src/pages/auth.jsx }TypeScript 项目将 import 路径改为src/pages/auth.tsx。接下来在src/pages/auth.{jsx,tsx}中定义这些页面的 React 组件。步骤 6创建客户端页面:::info 这里使用 Tailwind CSS。 :::在src/pages目录下创建auth.{jsx,tsx}文件import { LoginForm } from wasp/client/auth export function Login() { return ( Layout LoginForm / /Layout ) } // 用于居中内容的布局组件 export function Layout({ children }) { return ( div classNamew-full h-full bg-white div classNamemin-w-full min-h-[75vh] flex items-center justify-center div classNamew-full h-full max-w-sm p-5 bg-white div{children}/div /div /div /div ) }TypeScript 版本仅需为Layout的 props 补充类型标注{ children }: { children: React.ReactNode }。这里导入的是 Wasp 生成的 Auth UI 组件关于这些组件的更多说明见 Auth UI 文档。完成以上步骤后运行wasp db migrate-dev和wasp start就能得到一个带 GitHub 认证、可运行的完整应用。若要保护特定页面对未认证用户隐藏可参考 使用认证overview。默认行为首次登录即自动建号当用户首次通过 GitHub 登录时Wasp 会创建一个新用户账户并将其与所选认证提供方的账户关联用于后续登录见 _default-behaviour.md。启用方式非常简单在auth.methods字典中加入gitHub: {}即可app myApp { wasp: { version: ^0.14.0 }, title: My App, auth: { userEntity: User, methods: { gitHub: {} }, onAuthFailedRedirectTo: /login }, }覆盖机制userSignupFields 与 configFn默认情况下Wasp不会存储从社交登录提供方接收到的任何信息只保存提供方特定的用户 ID见 _override-intro.md。要覆盖默认行为可以使用两种机制userSignupFields定义注册过程中需要在User上设置的额外字段configFn自定义 OAuth 提供方的配置如 scopes。从 GitHub 接收到的数据Wasp 通过 GitHub API 的/user和/user/emails两个端点获取用户数据见 _override-example-intro.md。/user端点返回的数据形如{ login: octocat, id: 1, name: monalisa octocat, avatar_url: https://github.com/images/error/octocat_happy.gif, gravatar_id: , // ... }/user/emails端点返回的数据形如[ { email: octocatgithub.com, verified: true, primary: true, visibility: public } ]:::info 两个端点数据的合并 在userSignupFields收到的对象中邮箱位于emails属性中。这是因为当请求了user或user:emailscope 时Wasp 会合并/user与/user/emails两个端点的数据。 :::能接收到哪些字段取决于你请求的 scopes。默认情况下 Wasp 不指定任何 scope如果需要获取邮箱必须在configFn函数中指定user或user:emailscope。关于 GitHub 返回数据的完整、最新说明请参考 GitHub API 官方文档Get the authenticated user。使用接收到的数据完整示例当用户通过社交登录时后端会收到一些用户数据Wasp 允许你在userSignupFields的 getter 中访问这些数据。例如User实体可以包含displayName字段并根据提供方返回的详情进行填充同时也可以用configFn自定义提供方配置。下面用一个示例同时展示这两个字段的用法app myApp { wasp: { version: ^0.14.0 }, title: My App, auth: { userEntity: User, methods: { gitHub: { configFn: import { getConfig } from src/auth/github.js, userSignupFields: import { userSignupFields } from src/auth/github.js } }, onAuthFailedRedirectTo: /login }, }对应的schema.prismamodel User { id Int id default(autoincrement()) username String unique displayName String } // ...对应的src/auth/github.jsexport const userSignupFields { username: () hardcoded-username, displayName: (data) data.profile.name, }; export function getConfig() { return { scopes: [user], }; }TypeScript 版本使用 Wasp 自动生成的类型辅助函数defineUserSignupFields见 _getuserfields-type.mdimport { defineUserSignupFields } from wasp/server/auth export const userSignupFields defineUserSignupFields({ username: () hardcoded-username, displayName: (data: any) data.profile.name, }) export function getConfig() { return { scopes: [user], } }这里getConfig请求了userscope因此userSignupFields中的 getter 可以访问到 GitHub 返回的 profile 数据displayName: (data) data.profile.name把 GitHub 账号昵称写入User.displayName。userSignupFields的通用语义是定义注册过程中需要在User上设置的全部额外字段。例如如果User实体包含address和phone字段可以这样定义见 _user-signup-fields-explainer.mdimport { defineUserSignupFields } from wasp/server/auth export const userSignupFields defineUserSignupFields({ address: (data) { if (!data.address) { throw new Error(Address is required) } return data.address } phone: (data) data.phone, })getter 中抛出的错误会中断注册流程可用来实现必填字段校验。使用认证访问登录用户的 GitHub ID关于登出按钮的配置以及如何在客户端、服务端代码中获取已登录用户可参考 使用认证overview。当你在客户端或服务端拿到user对象后见 获取已登录用户可以像下面这样访问用户的 GitHub ID见 _github-data.mdconst githubIdentity user.identities.github // GitHub User ID例如 12345678 githubIdentity.id更多关于访问用户认证字段的说明见 Accessing User Data。API Reference提供方特有的行为归结为实现两个函数configFn与userSignupFields。以下引用展示了如何定义这两者所有提供方通用行为请参见 通用 API Reference。在main.wasp中启用并挂载这两个函数app myApp { wasp: { version: ^0.14.0 }, title: My App, auth: { userEntity: User, methods: { gitHub: { configFn: import { getConfig } from src/auth/github.js, userSignupFields: import { userSignupFields } from src/auth/github.js } }, onAuthFailedRedirectTo: /login }, }gitHub字典支持以下属性configFn: ExtImport该函数返回一个对象其中包含 OAuth 提供方的 scopes。export function getConfig() { return { scopes: [], } }通过调整scopes数组即可控制授权范围默认不传 scope请求邮箱需加入user或user:email。userSignupFields: ExtImport定义注册时需要在User上设置的额外字段getter 接收提供方返回的用户数据TypeScript 中可用defineUserSignupFields获得类型提示。关于该函数的详细说明见 定义额外字段。源码侧的实现原理在 Wasp 0.14 的生成器模板中GitHub 提供方的实现位于 waspc/data/Generator/templates/sdk/wasp/server/auth/oauth/providers/github.ts。可以看到它基于arctic库的GitHub类创建 OAuth 客户端并直接读取服务端环境变量GITHUB_CLIENT_ID与GITHUB_CLIENT_SECRET然后通过defineProvider注册为名为github的提供方import { GitHub } from arctic; import { defineProvider } from ../provider.js; import { env } from ../../../env.js; const oAuthClient new GitHub( env.GITHUB_CLIENT_ID, env.GITHUB_CLIENT_SECRET, ); export const github defineProvider({ id, displayName, oAuthClient, });这也解释了为什么GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET必须在.env.server中显式提供它们是arcticOAuth 客户端构造函数的直接参数。同时waspc/data/Generator/templates/sdk/wasp/server/env.ts 中的 zod 校验会在启用 GitHub 认证时强制要求这两个变量存在缺少任一变量都会导致服务端启动失败并给出明确报错信息。在客户端侧Wasp 还会生成wasp/client/auth的 GitHub 相关 API见 waspc/data/Generator/templates/sdk/wasp/client/auth/github.ts 与 index.ts而前文使用的LoginForm等 Auth UI 组件则在 waspc/data/Generator/templates/sdk/wasp/auth/forms 目录下定义——它们会自动渲染使用 GitHub 登录按钮并走完 OAuth 跳转、回调、建号的全流程。至此你已经完成了 GitHub 认证的接入声明式配置、环境变量注入、登录页搭建、用户数据定制以及对底层实现路径的完整了解。接下来可以在此基础上扩展User实体的业务字段或参考 使用认证overview 为不同页面添加登录保护。【免费下载链接】waspThe batteries-included full-stack framework for the AI era. Develop JS/TS web apps (React, Node.js, and Prisma) using declarative code that abstracts away complex full-stack features like auth, background jobs, RPC, email sending, end-to-end type safety, single-command deployment, and more.项目地址: https://gitcode.com/GitHub_Trending/wa/wasp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考