Wasp 部署实战外部认证Google / 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导读在 Wasp 应用中启用 Google、GitHub 等外部社交认证后除了在main.wasp声明认证方法和在本地.env.server配置密钥外生产部署时还必须把这些密钥以环境变量或平台 secrets的形式注入运行中的服务器——这一步漏掉轻则后端启动失败重则 OAuth 登录流程直接报错。本文以 Wasp 0.11.8 版本文档中的部署提醒为切入点结合仓库内的部署指南与生成器源码系统讲解 Wasp 应用部署时需要设置的全部环境变量、外部认证变量的配置位置与校验机制并给出 Fly.io、Netlify、Railway、Heroku 四大平台的实操命令。一、为什么部署时不能忽略外部认证环境变量在 部署提醒文档 中Wasp 明确提示如果你的应用使用了 Wasp 支持的外部认证方法例如 Google 或 GitHub请确保设置了必要necessary的环境变量。这句话的根源在于Wasp 生成的服务器代码在启动时就会读取并校验这些变量。在仓库的生成器模板 wasp/server/env.ts 中每个启用的认证提供方都会向服务端环境变量 schema 注入对应的必填校验项例如{# enabledAuthProviders.isGoogleAuthEnabled } GOOGLE_CLIENT_ID: z.string({ error: getRequiredEnvVarErrorMessage(Google auth provider, GOOGLE_CLIENT_ID), }), GOOGLE_CLIENT_SECRET: z.string({ error: getRequiredEnvVarErrorMessage(Google auth provider, GOOGLE_CLIENT_SECRET), }), {/ enabledAuthProviders.isGoogleAuthEnabled }GitHub 提供方同理GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET。也就是说只要你在main.wasp的auth.methods里声明了google: {}或gitHub: {}生成的服务器就会把这些变量视为必填——一旦缺失启动阶段的校验便会失败并抛出错误。同时OAuth 客户端对象在模块加载阶段就直接从环境变量构造。查看 Google 提供方模板 providers/google.tsconst oAuthClient new Google( env.GOOGLE_CLIENT_ID, env.GOOGLE_CLIENT_SECRET, getRedirectUriForCallback(id).toString(), );GitHub 提供方模板 providers/github.ts 也是同样模式const oAuthClient new GitHub( env.GITHUB_CLIENT_ID, env.GITHUB_CLIENT_SECRET, );因此可以推断外部认证密钥不只是登录时才用到而是服务器进程初始化时就需要加载的配置项这正是不论部署到哪家平台都必须显式设置它们的根本原因。二、Wasp 应用的部署模型与服务器必备环境变量要理解外部认证变量放在哪里先要清楚 Wasp 应用的部署结构。根据 手动部署文档部署 Wasp 应用分为四步用wasp build生成可部署代码输出到.wasp/build/部署 API 服务器后端部署 Web 客户端前端部署 PostgreSQL 数据库并保持其运行。其中后端 Docker 镜像运行在宿主平台上时必须注入以下环境变量变量用途示例PORT服务器监听 HTTP 请求的端口号3001DATABASE_URL要连接的 PostgreSQL 数据库连接串postgresql://mydbuser:mypasslocalhost:5432/nameofmydbWASP_WEB_CLIENT_URL前端部署后的访问地址用于正确配置同源策略CORS头https://app-name.netlify.appJWT_SECRET使用 Waspauth功能时才需要随机字符串长度至少 32 字符随机生成的强密钥注意wasp build在数据库为 SQLite默认数据库时无法构建生产部署前必须先切换到 PostgreSQL迁移步骤见 数据库文档。在这四项基础变量之上只要应用启用了外部认证就需要追加对应提供方的CLIENT_ID与CLIENT_SECRET变量——这正是部署提醒文档要强调的补充项。三、外部认证提供方对应的环境变量清单Wasp 支持的外部认证提供方均遵循提供方名大写 _CLIENT_ID/_CLIENT_SECRET的命名约定。各提供方的完整配置说明可参考对应文档GoogleGOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET见 Google 社交认证文档GitHubGITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET见 GitHub 社交认证文档。3.1 本地开发时的配置.env.server在开发阶段这些密钥写入项目根目录的.env.server文件例如 GoogleGOOGLE_CLIENT_IDyour-google-client-id GOOGLE_CLIENT_SECRETyour-google-client-secretGitHub 则对应GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret密钥本身来源于你在 Google Cloud Console / GitHub OAuth Apps 中创建 OAuth 应用时获得的 Client ID 与 Client Secret。注意 Google 的 Authorized redirect URIs 中要包含本地地址http://localhost:3000/auth/login/google以及生产服务器地址https://your-host/auth/login/google。3.2 生产环境同一变量、不同注入方式生产环境不再读取.env.server而是把同样的变量名注入宿主平台。以 Fly.io 为例flyctl secrets set GOOGLE_CLIENT_IDyour-google-client-id flyctl secrets set GOOGLE_CLIENT_SECRETyour-google-client-secret或 GitHubflyctl secrets set GITHUB_CLIENT_IDyour-github-client-id flyctl secrets set GITHUB_CLIENT_SECRETyour-github-client-secret务必保持变量名与本地完全一致因为生成的服务器代码只按这些固定名称从env读取见上文提供方模板源码改名将导致读取不到配置。四、四大部署平台的实操在哪注入这些变量4.1 Fly.io服务器 数据库在 Fly.io 部署章节 中构建完成后进入.wasp/build/先执行flyctl launch --remote-only创建应用与数据库创建时会自动设置DATABASE_URL再统一设置服务器变量flyctl secrets set PORT8080 flyctl secrets set JWT_SECRETrandom_string_at_least_32_characters_long flyctl secrets set WASP_WEB_CLIENT_URLurl_of_where_frontend_will_be_deployed flyctl secrets set GOOGLE_CLIENT_IDyour-google-client-id flyctl secrets set GOOGLE_CLIENT_SECRETyour-google-client-secret如果前端地址还未确定WASP_WEB_CLIENT_URL可以等前端部署完成后再补设。全部设置完成后可用以下命令核对注意 secrets 会以哈希形式显示以保护敏感数据flyctl secrets list最后执行部署flyctl deploy --remote-only --config ../../fly.toml提示wasp build每次会清空.wasp/build/目录因此建议把fly.toml复制到 Wasp 项目根目录保存之后用flyctl deploy --config path引用也可以随时用flyctl config save -a app-name从远端状态重新生成fly.toml。4.2 Netlify前端静态托管Netlify 只承载前端静态文件本身不需要注入认证密钥但前端部署后产生的 URL形如https://app-name.netlify.app必须回填到服务器侧的WASP_WEB_CLIENT_URL部署文档中明确要求在服务器托管环境如 Fly.io 或 Heroku中把该 URL 设置为WASP_WEB_CLIENT_URL环境变量保证 CORS 与 OAuth 回调配置正确。前端构建与发布命令# 在 .wasp/build/web-app 下 npm install REACT_APP_API_URLurl_to_wasp_backend npm run build netlify deploy --prod4.3 Railway服务器 客户端 数据库在 Railway 部署章节 中创建PostgreSQL、server、client三个资源后在 Railway Dashboard 的Settings Variables标签页为server服务配置变量通过Variable reference选择DATABASE_URL自动填充正确值添加WASP_WEB_CLIENT_URL填入client服务的域名如https://client-production-XXXX.up.railway.app添加JWT_SECRET至少 32 字符的随机字符串添加外部认证变量GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET或 GitHub 对应变量。随后在.wasp/build/目录执行railway link关联项目并用railway up部署提示选择 Service 时选server。4.4 Heroku服务器 数据库在 Heroku 部署章节 中创建应用与heroku-postgresql:mini数据库后DATABASE_URL与PORT均由 Heroku 自动提供只需显式设置其余变量heroku config:set --app app-name JWT_SECRETrandom_string_at_least_32_characters_long heroku config:set --app app-name WASP_WEB_CLIENT_URLurl_of_where_frontend_will_be_deployed heroku config:set --app app-name GOOGLE_CLIENT_IDyour-google-client-id heroku config:set --app app-name GOOGLE_CLIENT_SECRETyour-google-client-secret之后依次执行heroku container:login、heroku container:push --app app-name web、heroku container:release --app app-name web完成后端部署。若使用 Apple Silicon 机器需改用docker buildx build --platform linux/amd64构建后手动 push 到registry.heroku.com/app-name/web。若你的应用使用pg-boss作为 Jobs 执行器且部署到 Heroku还需额外设置PG_BOSS_NEW_OPTIONS为{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}详见部署文档中的注意事项因为 Heroku 要求 SSL 连接且使用自签名证书。五、一条龙部署wasp deployCLI 与免手配如果你不想手动逐条设置 secretsWasp 还提供了自动化部署命令。查看 CLI 部署文档 中的 Fly.io 部分wasp deploy fly launch/wasp deploy flyWasp CLI 会一次性完成服务器部署、客户端部署和数据库创建并支持单命令重新部署。不过需要注意即使走 CLI 自动化外部认证的CLIENT_ID/CLIENT_SECRET这类平台 secrets 通常仍需按平台要求单独配置或预先注入自动化流程并不会替你生成 OAuth 密钥本身——密钥始终来源于你在 Google / GitHub 开发者控制台创建的应用。六、部署后验证清单为避免前端能打开、登录却 500的典型事故按以下顺序自检后端启动成功确认PORT、DATABASE_URL、JWT_SECRET、WASP_WEB_CLIENT_URL均已设置且值正确外部认证变量齐全对照main.wasp中auth.methods声明的提供方逐一确认其_CLIENT_ID与_CLIENT_SECRET已注入可通过flyctl secrets list、heroku config等命令核对OAuth 回调地址匹配在 Google / GitHub OAuth 应用设置中将生产服务器的/auth/login/provider回调 URL 加入 Authorized redirect URIs开发环境为http://localhost:3000/auth/login/google前端 URL 回填确认WASP_WEB_CLIENT_URL指向已部署的静态站点地址端到端登录测试使用无痕窗口走一遍完整的第三方登录流程。七、小结外部认证是 Wasp 开箱即用的核心能力之一但它跨越了本地开发配置与生产部署注入两个环境。关键结论可以归纳为三点变量名固定且必填只要在main.wasp启用了 Google / GitHub 等提供方生成的服务器启动时就会通过 env.ts 中的 zod schema 校验对应*_CLIENT_ID/*_CLIENT_SECRET缺失即报错注入平台而非文件生产环境不再读取.env.server必须通过各平台Fly.io 的flyctl secrets set、Heroku 的heroku config:set、Railway 的 Variables 面板注入同名变量部署提醒的落点部署提醒文档 正是部署文档手动部署 与 CLI 部署为使用外部认证的应用打上的必读补丁——把它和其他服务器变量一起在部署时就配齐就能避免上线后才发现登录功能不可用的尴尬。【免费下载链接】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 部署实战：外部认证（Google / GitHub 等）环境变量在生产环境的完整配置指南
Wasp 部署实战外部认证Google / 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导读在 Wasp 应用中启用 Google、GitHub 等外部社交认证后除了在main.wasp声明认证方法和在本地.env.server配置密钥外生产部署时还必须把这些密钥以环境变量或平台 secrets的形式注入运行中的服务器——这一步漏掉轻则后端启动失败重则 OAuth 登录流程直接报错。本文以 Wasp 0.11.8 版本文档中的部署提醒为切入点结合仓库内的部署指南与生成器源码系统讲解 Wasp 应用部署时需要设置的全部环境变量、外部认证变量的配置位置与校验机制并给出 Fly.io、Netlify、Railway、Heroku 四大平台的实操命令。一、为什么部署时不能忽略外部认证环境变量在 部署提醒文档 中Wasp 明确提示如果你的应用使用了 Wasp 支持的外部认证方法例如 Google 或 GitHub请确保设置了必要necessary的环境变量。这句话的根源在于Wasp 生成的服务器代码在启动时就会读取并校验这些变量。在仓库的生成器模板 wasp/server/env.ts 中每个启用的认证提供方都会向服务端环境变量 schema 注入对应的必填校验项例如{# enabledAuthProviders.isGoogleAuthEnabled } GOOGLE_CLIENT_ID: z.string({ error: getRequiredEnvVarErrorMessage(Google auth provider, GOOGLE_CLIENT_ID), }), GOOGLE_CLIENT_SECRET: z.string({ error: getRequiredEnvVarErrorMessage(Google auth provider, GOOGLE_CLIENT_SECRET), }), {/ enabledAuthProviders.isGoogleAuthEnabled }GitHub 提供方同理GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET。也就是说只要你在main.wasp的auth.methods里声明了google: {}或gitHub: {}生成的服务器就会把这些变量视为必填——一旦缺失启动阶段的校验便会失败并抛出错误。同时OAuth 客户端对象在模块加载阶段就直接从环境变量构造。查看 Google 提供方模板 providers/google.tsconst oAuthClient new Google( env.GOOGLE_CLIENT_ID, env.GOOGLE_CLIENT_SECRET, getRedirectUriForCallback(id).toString(), );GitHub 提供方模板 providers/github.ts 也是同样模式const oAuthClient new GitHub( env.GITHUB_CLIENT_ID, env.GITHUB_CLIENT_SECRET, );因此可以推断外部认证密钥不只是登录时才用到而是服务器进程初始化时就需要加载的配置项这正是不论部署到哪家平台都必须显式设置它们的根本原因。二、Wasp 应用的部署模型与服务器必备环境变量要理解外部认证变量放在哪里先要清楚 Wasp 应用的部署结构。根据 手动部署文档部署 Wasp 应用分为四步用wasp build生成可部署代码输出到.wasp/build/部署 API 服务器后端部署 Web 客户端前端部署 PostgreSQL 数据库并保持其运行。其中后端 Docker 镜像运行在宿主平台上时必须注入以下环境变量变量用途示例PORT服务器监听 HTTP 请求的端口号3001DATABASE_URL要连接的 PostgreSQL 数据库连接串postgresql://mydbuser:mypasslocalhost:5432/nameofmydbWASP_WEB_CLIENT_URL前端部署后的访问地址用于正确配置同源策略CORS头https://app-name.netlify.appJWT_SECRET使用 Waspauth功能时才需要随机字符串长度至少 32 字符随机生成的强密钥注意wasp build在数据库为 SQLite默认数据库时无法构建生产部署前必须先切换到 PostgreSQL迁移步骤见 数据库文档。在这四项基础变量之上只要应用启用了外部认证就需要追加对应提供方的CLIENT_ID与CLIENT_SECRET变量——这正是部署提醒文档要强调的补充项。三、外部认证提供方对应的环境变量清单Wasp 支持的外部认证提供方均遵循提供方名大写 _CLIENT_ID/_CLIENT_SECRET的命名约定。各提供方的完整配置说明可参考对应文档GoogleGOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET见 Google 社交认证文档GitHubGITHUB_CLIENT_ID、GITHUB_CLIENT_SECRET见 GitHub 社交认证文档。3.1 本地开发时的配置.env.server在开发阶段这些密钥写入项目根目录的.env.server文件例如 GoogleGOOGLE_CLIENT_IDyour-google-client-id GOOGLE_CLIENT_SECRETyour-google-client-secretGitHub 则对应GITHUB_CLIENT_IDyour-github-client-id GITHUB_CLIENT_SECRETyour-github-client-secret密钥本身来源于你在 Google Cloud Console / GitHub OAuth Apps 中创建 OAuth 应用时获得的 Client ID 与 Client Secret。注意 Google 的 Authorized redirect URIs 中要包含本地地址http://localhost:3000/auth/login/google以及生产服务器地址https://your-host/auth/login/google。3.2 生产环境同一变量、不同注入方式生产环境不再读取.env.server而是把同样的变量名注入宿主平台。以 Fly.io 为例flyctl secrets set GOOGLE_CLIENT_IDyour-google-client-id flyctl secrets set GOOGLE_CLIENT_SECRETyour-google-client-secret或 GitHubflyctl secrets set GITHUB_CLIENT_IDyour-github-client-id flyctl secrets set GITHUB_CLIENT_SECRETyour-github-client-secret务必保持变量名与本地完全一致因为生成的服务器代码只按这些固定名称从env读取见上文提供方模板源码改名将导致读取不到配置。四、四大部署平台的实操在哪注入这些变量4.1 Fly.io服务器 数据库在 Fly.io 部署章节 中构建完成后进入.wasp/build/先执行flyctl launch --remote-only创建应用与数据库创建时会自动设置DATABASE_URL再统一设置服务器变量flyctl secrets set PORT8080 flyctl secrets set JWT_SECRETrandom_string_at_least_32_characters_long flyctl secrets set WASP_WEB_CLIENT_URLurl_of_where_frontend_will_be_deployed flyctl secrets set GOOGLE_CLIENT_IDyour-google-client-id flyctl secrets set GOOGLE_CLIENT_SECRETyour-google-client-secret如果前端地址还未确定WASP_WEB_CLIENT_URL可以等前端部署完成后再补设。全部设置完成后可用以下命令核对注意 secrets 会以哈希形式显示以保护敏感数据flyctl secrets list最后执行部署flyctl deploy --remote-only --config ../../fly.toml提示wasp build每次会清空.wasp/build/目录因此建议把fly.toml复制到 Wasp 项目根目录保存之后用flyctl deploy --config path引用也可以随时用flyctl config save -a app-name从远端状态重新生成fly.toml。4.2 Netlify前端静态托管Netlify 只承载前端静态文件本身不需要注入认证密钥但前端部署后产生的 URL形如https://app-name.netlify.app必须回填到服务器侧的WASP_WEB_CLIENT_URL部署文档中明确要求在服务器托管环境如 Fly.io 或 Heroku中把该 URL 设置为WASP_WEB_CLIENT_URL环境变量保证 CORS 与 OAuth 回调配置正确。前端构建与发布命令# 在 .wasp/build/web-app 下 npm install REACT_APP_API_URLurl_to_wasp_backend npm run build netlify deploy --prod4.3 Railway服务器 客户端 数据库在 Railway 部署章节 中创建PostgreSQL、server、client三个资源后在 Railway Dashboard 的Settings Variables标签页为server服务配置变量通过Variable reference选择DATABASE_URL自动填充正确值添加WASP_WEB_CLIENT_URL填入client服务的域名如https://client-production-XXXX.up.railway.app添加JWT_SECRET至少 32 字符的随机字符串添加外部认证变量GOOGLE_CLIENT_ID/GOOGLE_CLIENT_SECRET或 GitHub 对应变量。随后在.wasp/build/目录执行railway link关联项目并用railway up部署提示选择 Service 时选server。4.4 Heroku服务器 数据库在 Heroku 部署章节 中创建应用与heroku-postgresql:mini数据库后DATABASE_URL与PORT均由 Heroku 自动提供只需显式设置其余变量heroku config:set --app app-name JWT_SECRETrandom_string_at_least_32_characters_long heroku config:set --app app-name WASP_WEB_CLIENT_URLurl_of_where_frontend_will_be_deployed heroku config:set --app app-name GOOGLE_CLIENT_IDyour-google-client-id heroku config:set --app app-name GOOGLE_CLIENT_SECRETyour-google-client-secret之后依次执行heroku container:login、heroku container:push --app app-name web、heroku container:release --app app-name web完成后端部署。若使用 Apple Silicon 机器需改用docker buildx build --platform linux/amd64构建后手动 push 到registry.heroku.com/app-name/web。若你的应用使用pg-boss作为 Jobs 执行器且部署到 Heroku还需额外设置PG_BOSS_NEW_OPTIONS为{connectionString:REGULAR_HEROKU_DATABASE_URL,ssl:{rejectUnauthorized:false}}详见部署文档中的注意事项因为 Heroku 要求 SSL 连接且使用自签名证书。五、一条龙部署wasp deployCLI 与免手配如果你不想手动逐条设置 secretsWasp 还提供了自动化部署命令。查看 CLI 部署文档 中的 Fly.io 部分wasp deploy fly launch/wasp deploy flyWasp CLI 会一次性完成服务器部署、客户端部署和数据库创建并支持单命令重新部署。不过需要注意即使走 CLI 自动化外部认证的CLIENT_ID/CLIENT_SECRET这类平台 secrets 通常仍需按平台要求单独配置或预先注入自动化流程并不会替你生成 OAuth 密钥本身——密钥始终来源于你在 Google / GitHub 开发者控制台创建的应用。六、部署后验证清单为避免前端能打开、登录却 500的典型事故按以下顺序自检后端启动成功确认PORT、DATABASE_URL、JWT_SECRET、WASP_WEB_CLIENT_URL均已设置且值正确外部认证变量齐全对照main.wasp中auth.methods声明的提供方逐一确认其_CLIENT_ID与_CLIENT_SECRET已注入可通过flyctl secrets list、heroku config等命令核对OAuth 回调地址匹配在 Google / GitHub OAuth 应用设置中将生产服务器的/auth/login/provider回调 URL 加入 Authorized redirect URIs开发环境为http://localhost:3000/auth/login/google前端 URL 回填确认WASP_WEB_CLIENT_URL指向已部署的静态站点地址端到端登录测试使用无痕窗口走一遍完整的第三方登录流程。七、小结外部认证是 Wasp 开箱即用的核心能力之一但它跨越了本地开发配置与生产部署注入两个环境。关键结论可以归纳为三点变量名固定且必填只要在main.wasp启用了 Google / GitHub 等提供方生成的服务器启动时就会通过 env.ts 中的 zod schema 校验对应*_CLIENT_ID/*_CLIENT_SECRET缺失即报错注入平台而非文件生产环境不再读取.env.server必须通过各平台Fly.io 的flyctl secrets set、Heroku 的heroku config:set、Railway 的 Variables 面板注入同名变量部署提醒的落点部署提醒文档 正是部署文档手动部署 与 CLI 部署为使用外部认证的应用打上的必读补丁——把它和其他服务器变量一起在部署时就配齐就能避免上线后才发现登录功能不可用的尴尬。【免费下载链接】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），仅供参考