Wasp 集成 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/waspWasp 内置了对 GitHub 第三方认证GitHub Authentication的开箱即用支持只需在声明式的main.wasp配置中开启gitHub方法并补齐 OAuth 应用与环境变量即可获得完整的使用 GitHub 账号登录能力。本文基于仓库 web/versioned_docs/version-0.17/auth/social-auth/github.md 展开带你走完从 Wasp 文件配置、Prisma User 实体、GitHub OAuth App 创建、环境变量注入到前端登录页面落地的全部步骤并深入讲解默认行为、configFn与userSignupFields两大扩展机制以及如何读取 GitHub 身份数据。读完本文你将能够在自己的 Wasp 应用中独立完成 GitHub 登录的接入与定制。GitHub Auth 的适用场景GitHub 认证特别适合面向开发者群体的应用大多数目标用户已经拥有 GitHub 账号允许他们用 GitHub 直接登录可以将注册流程缩短为一次点击显著降低注册门槛。在 Wasp 中开启 GitHub 认证只需一组固定步骤整体链路如下在 Wasp 文件main.wasp中启用 GitHub 认证。添加User实体schema.prisma。创建 GitHub OAuth App。添加认证所需的 Routes 与 Pages。在页面中使用 Wasp 生成的 Auth UI 组件。完成后的main.wasp结构大致如下// Configuring the social authentication app myApp { auth: { ... } } // Defining routes and pages route LoginRoute { ... } page LoginPage { ... }1. 在 main.wasp 中启用 GitHub 认证首先在main.wasp中配置app.auth对象app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { // 1. 指定 User 实体下一步定义 userEntity: User, methods: { // 2. 启用 GitHub Auth gitHub: {} }, onAuthFailedRedirectTo: /login }, }关键点说明userEntity: User指向你在 Prisma 中定义的User模型所有认证后的用户数据都会落在这个实体上。gitHub: {}以空字典形式开启 GitHub 认证表示使用 Wasp 提供的默认行为。onAuthFailedRedirectTo指定认证失败时前端重定向的路径这里指向即将创建的/login页面。从源码结构看Wasp 的 AppSpec 层把gitHub建模为Maybe ExternalAuthConfig见 App/Auth.hs并提供了isGitHubAuthEnabled这样的判定函数源码第 113 行说明 GitHub 认证是作为可选的、可配置的外部认证模块参与整个应用规格解析的。2. 添加 User 实体接着在schema.prisma中定义app.auth.userEntity指向的User模型// 3. 定义 user entity model User { id Int id default(autoincrement()) // 在这里添加你自己的字段 // ... }最小配置只需要一个主键id。如果后续需要使用userSignupFields写入来自 GitHub 的额外资料如用户名、展示名则需要在此模型中补充对应字段。仓库中ask-the-documents示例的 schema.prisma 就是一份可参考的真实实体定义。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下一步会用到。这里的回调地址/auth/github/callback与 Wasp 生成的 OAuth 流程端点一一对应——Wasp 会在运行时用这些凭据与 GitHub 完成授权码交换随后把用户身份写入User实体。4. 添加环境变量在项目根目录的.env.server文件中添加以下环境变量值取自上一步GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secretWasp 在构建/启动时读取这些变量注入服务端。注意它们属于服务端机密不应出现在客户端环境变量中。5. 添加认证所需的 Routes 和 Pages在main.wasp中定义认证路由与页面// ... route LoginRoute { path: /login, to: LoginPage } page LoginPage { component: import { Login } from src/pages/auth }React 组件将定义在src/pages/auth.{jsx,tsx}文件中。6. 创建客户端登录页面在src/pages目录下创建auth.{jsx,tsx}文件import type { ReactNode } from react import { LoginForm } from wasp/client/auth export function Login() { return ( Layout LoginForm / /Layout ) } // 一个用于居中对齐内容的布局组件 export function Layout({ children }: { children: ReactNode }) { return ( div classNameh-full w-full bg-white div classNameflex min-h-[75vh] min-w-full items-center justify-center div classNameh-full w-full max-w-sm bg-white p-5 div{children}/div /div /div /div ) }这里从wasp/client/auth导入了 Wasp 生成的 Auth UI 组件LoginForm并使用在页面中。该组件渲染时即包含 GitHub 登录按钮点击后跳转到 GitHub 授权页。示例使用 Tailwind CSS 进行样式排版你可以根据偏好换成任意样式方案关于 Auth UI 组件的完整用法可参考 auth/ui.md。值得留意的是Wasp 的生成器模板为客户端提供了独立的 GitHub 认证入口sdk/wasp/client/auth/github.ts 中导出了githubSignInUrl内部转发自auth/helpers/GitHub它正是客户端发起 GitHub OAuth 跳转的底层封装而 SocialIcons.tsx 等表单组件则负责渲染带品牌图标的社交登录按钮。这意味着从 UI 到跳转 URL整条 GitHub 登录链路都由 Wasp 的代码生成器自动产出开发者无需手写 OAuth 客户端逻辑。运行与验证完成上述配置后在项目根目录依次执行wasp db migrate-dev wasp start即可得到一个带认证能力的可运行应用。访问/login页面通过 GitHub 按钮完成登录。若要保护特定页面即对未认证用户隐藏请参考认证概览文档 overview.md。默认行为在auth.methods字典中加入gitHub: {}即使用默认设置app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { userEntity: User, methods: { gitHub: {} }, onAuthFailedRedirectTo: /login }, }默认行为包括当用户首次登录时Wasp 会创建一个新的用户账号并将其与所选认证提供方的账号关联用于后续登录。Wasp 默认不存储从社交登录提供方接收到的任何信息仅保存用户在提供方侧的 ID。因此如果你需要把 GitHub 返回的姓名、头像、邮箱等信息持久化到User实体就必须使用下面介绍的覆盖机制。覆盖默认行为configFn 与 userSignupFieldsWasp 提供两个机制来覆盖默认行为userSignupFields在注册首次登录时把提供方返回的数据写入User实体的自定义字段。configFn自定义 OAuth 提供方的配置例如申请更多 OAuth scope。当用户通过社交登录登录时后端会收到关于用户的一些数据。Wasp 允许你在userSignupFields的 getter 中访问这些数据。例如User实体可以包含一个displayName字段并依据提供方返回的信息来赋值。configFn则用于定制提供方的设置。从 GitHub 获取的数据Wasp 使用 GitHub 的 API 及其/user与/user/emails两个端点来获取用户数据。两个端点的数据会被合并在userSignupFields中收到的对象里邮箱位于emails属性中。这是因为当请求了user或user:emailscope 时Wasp 会把/user与/user/emails两个端点的数据合并在一起。/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 } ]你实际收到的字段取决于所请求的 scope。默认情况下 Wasp 不指定任何 scope如果需要获取邮箱必须在configFn函数中显式请求user或user:emailscope。关于 GitHub 返回字段的最新说明请以 GitHub 官方 API 文档为准。使用获取的数据完整示例假设User实体包含username与displayName两个字段我们希望用 GitHub 数据填充它们app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { userEntity: User, methods: { gitHub: { configFn: import { getConfig } from src/auth/github, userSignupFields: import { userSignupFields } from src/auth/github } }, onAuthFailedRedirectTo: /login }, }model User { id Int id default(autoincrement()) username String unique displayName String } // ...在src/auth/github.ts中实现两个导出函数import { defineUserSignupFields } from wasp/server/auth export const userSignupFields defineUserSignupFields({ username: () hardcoded-username, displayName: (data: any) data.profile.name, }) export function getConfig() { return { scopes: [user], } }要点拆解defineUserSignupFields由 Wasp 自动生成用于帮你正确地为userSignupFields对象标注类型。它定义的是注册过程中需要在User上设置的所有额外字段。例如User上有address、phone字段时可以这样定义src/auth.tsimport { 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 接收的data参数包含来自提供方的用户资料此处data.profile.name即 GitHub/user端点返回的name字段说明只有配置了configFn请求对应 scope相关数据才会出现。getConfig返回的scopes: [user]使 Wasp 在发起 GitHub 授权时请求userscope从而能够拿到/user/emails数据合并进emails属性。使用 Auth访问登录用户信息关于登出按钮的设置以及在客户端与服务端代码中获取已登录用户请阅读认证概览文档 overview.md。当你在客户端或服务端拿到user对象后可以这样访问用户的 GitHub IDconst githubIdentity user.identities.github // GitHub User ID例如 12345678 githubIdentity.id即 Wasp 会把各提供方的身份信息以identities.provider的形式挂载在user对象上github身份下保存着 GitHub 侧的用户 ID。关于认证字段的访问细节可参考 entities.md 中 Accessing the Auth Fields 一节。API 参考提供方特有的行为归结为实现两个函数configFn与userSignupFields。下面是main.wasp中的完整声明方式app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { userEntity: User, methods: { gitHub: { configFn: import { getConfig } from src/auth/github, userSignupFields: import { userSignupFields } from src/auth/github } }, onAuthFailedRedirectTo: /login }, }gitHub字典支持以下属性configFn: ExtImport该函数应返回包含 OAuth 提供方 scope 的对象export function getConfig() { return { scopes: [], } }userSignupFields: ExtImport定义注册过程中需要在User上设置的所有额外字段见上文defineUserSignupFields用法。关于userSignupFields函数的更多说明可参考认证概览文档 overview.md 中 Defining extra fields 一节。对于所有提供方通用的行为请参阅认证总览的 API Reference。此外仓库中 Auth.hs 从 AppSpec 层面定义了gitHub的可选配置结构是理解该声明背后解析与校验逻辑的源码入口感兴趣的读者可以进一步深入。【免费下载链接】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），仅供参考 Wasp 集成 GitHub OAuth 登录：从零配置到自定义数据扩展的完整指南
Wasp 集成 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/waspWasp 内置了对 GitHub 第三方认证GitHub Authentication的开箱即用支持只需在声明式的main.wasp配置中开启gitHub方法并补齐 OAuth 应用与环境变量即可获得完整的使用 GitHub 账号登录能力。本文基于仓库 web/versioned_docs/version-0.17/auth/social-auth/github.md 展开带你走完从 Wasp 文件配置、Prisma User 实体、GitHub OAuth App 创建、环境变量注入到前端登录页面落地的全部步骤并深入讲解默认行为、configFn与userSignupFields两大扩展机制以及如何读取 GitHub 身份数据。读完本文你将能够在自己的 Wasp 应用中独立完成 GitHub 登录的接入与定制。GitHub Auth 的适用场景GitHub 认证特别适合面向开发者群体的应用大多数目标用户已经拥有 GitHub 账号允许他们用 GitHub 直接登录可以将注册流程缩短为一次点击显著降低注册门槛。在 Wasp 中开启 GitHub 认证只需一组固定步骤整体链路如下在 Wasp 文件main.wasp中启用 GitHub 认证。添加User实体schema.prisma。创建 GitHub OAuth App。添加认证所需的 Routes 与 Pages。在页面中使用 Wasp 生成的 Auth UI 组件。完成后的main.wasp结构大致如下// Configuring the social authentication app myApp { auth: { ... } } // Defining routes and pages route LoginRoute { ... } page LoginPage { ... }1. 在 main.wasp 中启用 GitHub 认证首先在main.wasp中配置app.auth对象app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { // 1. 指定 User 实体下一步定义 userEntity: User, methods: { // 2. 启用 GitHub Auth gitHub: {} }, onAuthFailedRedirectTo: /login }, }关键点说明userEntity: User指向你在 Prisma 中定义的User模型所有认证后的用户数据都会落在这个实体上。gitHub: {}以空字典形式开启 GitHub 认证表示使用 Wasp 提供的默认行为。onAuthFailedRedirectTo指定认证失败时前端重定向的路径这里指向即将创建的/login页面。从源码结构看Wasp 的 AppSpec 层把gitHub建模为Maybe ExternalAuthConfig见 App/Auth.hs并提供了isGitHubAuthEnabled这样的判定函数源码第 113 行说明 GitHub 认证是作为可选的、可配置的外部认证模块参与整个应用规格解析的。2. 添加 User 实体接着在schema.prisma中定义app.auth.userEntity指向的User模型// 3. 定义 user entity model User { id Int id default(autoincrement()) // 在这里添加你自己的字段 // ... }最小配置只需要一个主键id。如果后续需要使用userSignupFields写入来自 GitHub 的额外资料如用户名、展示名则需要在此模型中补充对应字段。仓库中ask-the-documents示例的 schema.prisma 就是一份可参考的真实实体定义。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下一步会用到。这里的回调地址/auth/github/callback与 Wasp 生成的 OAuth 流程端点一一对应——Wasp 会在运行时用这些凭据与 GitHub 完成授权码交换随后把用户身份写入User实体。4. 添加环境变量在项目根目录的.env.server文件中添加以下环境变量值取自上一步GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secretWasp 在构建/启动时读取这些变量注入服务端。注意它们属于服务端机密不应出现在客户端环境变量中。5. 添加认证所需的 Routes 和 Pages在main.wasp中定义认证路由与页面// ... route LoginRoute { path: /login, to: LoginPage } page LoginPage { component: import { Login } from src/pages/auth }React 组件将定义在src/pages/auth.{jsx,tsx}文件中。6. 创建客户端登录页面在src/pages目录下创建auth.{jsx,tsx}文件import type { ReactNode } from react import { LoginForm } from wasp/client/auth export function Login() { return ( Layout LoginForm / /Layout ) } // 一个用于居中对齐内容的布局组件 export function Layout({ children }: { children: ReactNode }) { return ( div classNameh-full w-full bg-white div classNameflex min-h-[75vh] min-w-full items-center justify-center div classNameh-full w-full max-w-sm bg-white p-5 div{children}/div /div /div /div ) }这里从wasp/client/auth导入了 Wasp 生成的 Auth UI 组件LoginForm并使用在页面中。该组件渲染时即包含 GitHub 登录按钮点击后跳转到 GitHub 授权页。示例使用 Tailwind CSS 进行样式排版你可以根据偏好换成任意样式方案关于 Auth UI 组件的完整用法可参考 auth/ui.md。值得留意的是Wasp 的生成器模板为客户端提供了独立的 GitHub 认证入口sdk/wasp/client/auth/github.ts 中导出了githubSignInUrl内部转发自auth/helpers/GitHub它正是客户端发起 GitHub OAuth 跳转的底层封装而 SocialIcons.tsx 等表单组件则负责渲染带品牌图标的社交登录按钮。这意味着从 UI 到跳转 URL整条 GitHub 登录链路都由 Wasp 的代码生成器自动产出开发者无需手写 OAuth 客户端逻辑。运行与验证完成上述配置后在项目根目录依次执行wasp db migrate-dev wasp start即可得到一个带认证能力的可运行应用。访问/login页面通过 GitHub 按钮完成登录。若要保护特定页面即对未认证用户隐藏请参考认证概览文档 overview.md。默认行为在auth.methods字典中加入gitHub: {}即使用默认设置app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { userEntity: User, methods: { gitHub: {} }, onAuthFailedRedirectTo: /login }, }默认行为包括当用户首次登录时Wasp 会创建一个新的用户账号并将其与所选认证提供方的账号关联用于后续登录。Wasp 默认不存储从社交登录提供方接收到的任何信息仅保存用户在提供方侧的 ID。因此如果你需要把 GitHub 返回的姓名、头像、邮箱等信息持久化到User实体就必须使用下面介绍的覆盖机制。覆盖默认行为configFn 与 userSignupFieldsWasp 提供两个机制来覆盖默认行为userSignupFields在注册首次登录时把提供方返回的数据写入User实体的自定义字段。configFn自定义 OAuth 提供方的配置例如申请更多 OAuth scope。当用户通过社交登录登录时后端会收到关于用户的一些数据。Wasp 允许你在userSignupFields的 getter 中访问这些数据。例如User实体可以包含一个displayName字段并依据提供方返回的信息来赋值。configFn则用于定制提供方的设置。从 GitHub 获取的数据Wasp 使用 GitHub 的 API 及其/user与/user/emails两个端点来获取用户数据。两个端点的数据会被合并在userSignupFields中收到的对象里邮箱位于emails属性中。这是因为当请求了user或user:emailscope 时Wasp 会把/user与/user/emails两个端点的数据合并在一起。/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 } ]你实际收到的字段取决于所请求的 scope。默认情况下 Wasp 不指定任何 scope如果需要获取邮箱必须在configFn函数中显式请求user或user:emailscope。关于 GitHub 返回字段的最新说明请以 GitHub 官方 API 文档为准。使用获取的数据完整示例假设User实体包含username与displayName两个字段我们希望用 GitHub 数据填充它们app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { userEntity: User, methods: { gitHub: { configFn: import { getConfig } from src/auth/github, userSignupFields: import { userSignupFields } from src/auth/github } }, onAuthFailedRedirectTo: /login }, }model User { id Int id default(autoincrement()) username String unique displayName String } // ...在src/auth/github.ts中实现两个导出函数import { defineUserSignupFields } from wasp/server/auth export const userSignupFields defineUserSignupFields({ username: () hardcoded-username, displayName: (data: any) data.profile.name, }) export function getConfig() { return { scopes: [user], } }要点拆解defineUserSignupFields由 Wasp 自动生成用于帮你正确地为userSignupFields对象标注类型。它定义的是注册过程中需要在User上设置的所有额外字段。例如User上有address、phone字段时可以这样定义src/auth.tsimport { 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 接收的data参数包含来自提供方的用户资料此处data.profile.name即 GitHub/user端点返回的name字段说明只有配置了configFn请求对应 scope相关数据才会出现。getConfig返回的scopes: [user]使 Wasp 在发起 GitHub 授权时请求userscope从而能够拿到/user/emails数据合并进emails属性。使用 Auth访问登录用户信息关于登出按钮的设置以及在客户端与服务端代码中获取已登录用户请阅读认证概览文档 overview.md。当你在客户端或服务端拿到user对象后可以这样访问用户的 GitHub IDconst githubIdentity user.identities.github // GitHub User ID例如 12345678 githubIdentity.id即 Wasp 会把各提供方的身份信息以identities.provider的形式挂载在user对象上github身份下保存着 GitHub 侧的用户 ID。关于认证字段的访问细节可参考 entities.md 中 Accessing the Auth Fields 一节。API 参考提供方特有的行为归结为实现两个函数configFn与userSignupFields。下面是main.wasp中的完整声明方式app myApp { wasp: { version: {latestWaspVersion} }, title: My App, auth: { userEntity: User, methods: { gitHub: { configFn: import { getConfig } from src/auth/github, userSignupFields: import { userSignupFields } from src/auth/github } }, onAuthFailedRedirectTo: /login }, }gitHub字典支持以下属性configFn: ExtImport该函数应返回包含 OAuth 提供方 scope 的对象export function getConfig() { return { scopes: [], } }userSignupFields: ExtImport定义注册过程中需要在User上设置的所有额外字段见上文defineUserSignupFields用法。关于userSignupFields函数的更多说明可参考认证概览文档 overview.md 中 Defining extra fields 一节。对于所有提供方通用的行为请参阅认证总览的 API Reference。此外仓库中 Auth.hs 从 AppSpec 层面定义了gitHub的可选配置结构是理解该声明背后解析与校验逻辑的源码入口感兴趣的读者可以进一步深入。【免费下载链接】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），仅供参考