Folofollow开源贡献指南从 Corepack 环境准备到四端开发工作流与质量门禁【免费下载链接】follow Folo is the AI RSS Reader项目地址: https://gitcode.com/GitHub_Trending/fol/follow本文基于 FoloAI RSS 阅读器仓库follow的官方贡献文档 CONTRIBUTING.md 编写覆盖从 Corepack pnpm 环境准备、四种开发入口浏览器 / Electron / 外部 SSR / 移动端的完整操作步骤到提交前必须通过的质量门禁typecheck → lint → test。读完本篇你可以独立把该 monorepo 跑起来并对每一步命令背后的实现如__debug_proxy在线调试机制、移动端的 App Check 调试令牌有源码级的理解具备直接向该项目提交代码的基础。一、准备工作monorepo 结构与包管理器Folo 是一个由pnpm workspaces Turbo管理的 monorepo。在动手前需要先理解仓库的组织方式这决定了后续每条命令的作用范围根工作区定义在 pnpm-workspace.yaml包含apps/*、packages/**/*、apps/desktop/layer/*以及apps/mobile/web-app/html-renderer并排除了**/example目录四个主要应用分别是 apps/desktopElectron 桌面端Vite React 渲染层、apps/mobileExpo / React Native 移动端、apps/ssr用于外部分享的极简 SSR 站点、apps/landing落地页共享逻辑沉淀在packages/internal/*components、store、hooks、database 等。启用 Corepack官方要求贡献者先启用 Corepack 中声明的packageManager字段当前仓库锁定为pnpm10.17.0自动匹配正确的 pnpm 版本避免团队内包管理器版本漂移corepack enable corepack prepare从源码结构看这一机制被双重加固根package.json的prepare脚本为simple-git-hooks corepack prepare即pnpm install后会自动再次执行corepack prepare确保锁定的 pnpm 版本与 git hooks 同步就绪。安装依赖pnpm install需要注意 package.json 中配置了postinstall钩子postinstall: pnpm run build:packages, build:packages: turbo run build --filter\./packages/**/*\也就是说安装依赖的同时会用 Turbo 把所有packages/**下的内部包预先构建一遍。这也解释了为什么 AGENTS.md 中给出的Setup commands以pnpm install作为第一条——安装命令本身就是环境准备的一部分首次安装耗时会明显长于后续安装。二、四种开发入口CONTRIBUTING.md 提供了四条开发路径浏览器、Electron、外部 SSR Web、移动端。下面逐一展开并给出源码层面的佐证。2.1 浏览器开发推荐__debug_proxy调试入口官方推荐在浏览器中开发因为它体验更轻、更接近最终 Web 形态cd apps/desktop pnpm run dev:web该命令的实际定义在 apps/desktop/package.json 中dev:web: cross-env WEB_BUILD1 viteWEB_BUILD1标记这是一个纯 Web 构建不带 Electron 主进程。文档说明启动后会引导你访问https://app.folo.is/__debug_proxy从而复用线上 API 环境进行开发调试。这个__debug_proxy机制在源码中可以直接验证桌面端的 vite.config.ts 在构建时会把调试页写出到dist/__debug_proxy.html与dist/__debug_proxy/index.html并在开发模式打印两条调试地址——生产调试页https://app.folo.is/__debug_proxy.html与开发调试页https://dev.folo.is/__debug_proxy.html部署侧vercel.json 配置了重写规则把/__debug_proxy与/__debug_proxy/:path*请求统一落到__debug_proxy.html保证线上路径可用路由侧apps/desktop/layer/renderer/src/router.web.tsx 通过globalThis[__DEBUG_PROXY__]或 pathname 前缀/__debug_proxy判断是否处于调试代理运行时此时改用createHashRouter因为线上页面并非部署在站点根路径下hash 路由可避免刷新 404。也就是说本地 Vite dev server 提供 JS 资源线上__debug_proxy页面提供 API 与域名环境二者结合即构成浏览器里开发、打线上后端的完整链路。2.2 Electron 开发若需要在桌面壳内开发CONTRIBUTING.md 给出的步骤为# 0. 进入目录 cd apps/desktop # 1. 复制示例环境变量文件 cp .env.example .env # 2. 将 .env 中的 VITE_API_URL 设置为 https://api.follow.is # 3. 启动开发服务器 pnpm run dev:electrondev:electron实际执行的是electron-vite dev见 apps/desktop/package.json即同时启动 Electron 主进程与渲染进程。关于.env文件仓库内已提供 apps/desktop/.env.example包含以下变量变量示例值说明VITE_WEB_URLhttp://localhost:5173本地 Web 渲染地址VITE_API_URLhttp://localhost:3000API 后端地址文档要求改为https://api.follow.isVITE_IMGPROXY_URLhttp://localhost:2873图片代理地址VITE_SENTRY_DSN空错误上报 DSNVITE_BUILD_TYPEproduction构建类型VITE_INBOXES_EMAILfollow.re收件箱邮箱VITE_PUBLIC_POSTHOG_KEY/VITE_PUBLIC_POSTHOG_HOST空埋点配置文档中的排障提示如果遇到登录问题可以把浏览器 Cookie 里的__Secure-better-auth.session_token复制到应用中复用已有的浏览器会话完成登录态。2.3 外部 SSR Web 应用开发SSR 站点对应 apps/ssr 目录用于外部分享场景例如分享内容页的服务端渲染版本。启动方式最简单cd apps/ssr pnpm run dev另外根 package.json 还提供了一条dev:web脚本turbo run follow/web#dev follow/ssr#dev可并行拉起 desktop 渲染端与 SSR 端适合需要两侧同时联动的改动。2.4 移动端开发需要 MacCONTRIBUTING.md 明确标注移动端开发需要Mac 设备并已安装 Xcode 及相应依赖。步骤如下# 1. 进入目录 cd apps/mobile # 2. 复制环境变量文件并写入调试令牌 cp .env.example .env echo EXPO_PUBLIC_APP_CHECK_DEBUG_TOKENxxx .env # 也可以手动在 .env 中添加 EXPO_PUBLIC_APP_CHECK_DEBUG_TOKENxxx # 注意令牌值可以是任意字符串 # 3. 从源码构建并安装 Folo(dev) 应用耗时较长只需做一次 pnpm expo prebuild --clean # 可选 pnpm run ios # 4. 启动开发服务器 pnpm run devEXPO_PUBLIC_APP_CHECK_DEBUG_TOKEN并不是随意要求——从源码 apps/mobile/src/initialize/app-check.ts 可以看到它的用途provider.configure({ apple: { provider: __DEV__ ? debug : appAttest, debugToken: env.APP_CHECK_DEBUG_TOKEN, }, android: { provider: __DEV__ ? debug : playIntegrity, debugToken: env.APP_CHECK_DEBUG_TOKEN, }, isTokenAutoRefreshEnabled: true, })即开发态__DEV__下 Firebase App Check 使用debugprovider 并注入该调试令牌生产态则切换为 iOS 的appAttest/ Android 的playIntegrity。这就是为什么该令牌值可以是任意字符串它在 debug provider 下由开发者自行生成并配置到 Firebase 控制台即可。仓库中的 apps/mobile/.env.example 也同时预留了SENTRY_AUTH_TOKEN变量位。开发 iOS 原生模块需要修改FollowNative原生模块时对应 apps/mobile/native 下的 Expo 原生模块按文档操作# 1. 进入 iOS 工程目录 cd apps/mobile/ios # 2. 在 Xcode 中打开工作区 open Folo.xcworkspace # 3. 在左侧 Pods 目录中选择 FollowNative 后直接 Build Run原生模块本身是一个 Expo module见 apps/mobile/native/expo-module.config.jsonnative/ios下包含 Swift 实现通过 CocoaPods 以FollowNative名义接入工程因此改动后需在 Xcode 中重新编译 Pods 才会生效。三、质量门禁与代码规范CONTRIBUTING.md 的 Contribution Guidelines 要求代码遵循项目编码规范、提交信息清晰简洁、为改动附带相关测试、按需更新文档。落到可执行层面AGENTS.md 给出了明确的提交前必过质量门禁并且顺序是固定的# 1) 先跑类型检查必须 pnpm run typecheck # 2) 再跑 Lint 并自动修复 pnpm run lint:fix # 3) 最后跑测试 pnpm run test对应的根 package.json 脚本值得细看typecheck: turbo typecheck, lint: pnpm run lint:tsl eslint, lint:fix: eslint --fix, lint:tsl: tsslint --project apps/*/tsconfig.json, test: cross-env CI1 pnpm --recursive run test即 lint 实际包含两层tsslint基于 ts 项目的类型级 lint作用于所有 app 的 tsconfig加eslint测试则以CI1递归执行各包的测试测试框架为 Vitest测试文件与源码就近放置如 apps/cli/src/args.test.ts 这类同名*.test.ts文件。此外仓库还配了自动化护栏提交时会额外触发simple-git-hooks的 pre-commit 钩子执行pnpm exec lint-stagedlint-staged对暂存文件统一执行eslint --fix与prettier --write并对locales/**/*.json额外运行dedupe:locales即eslint --fix locales/**保持多语言词条排序一致对apps/mobile/src/**触发构建号自增脚本。代码风格上的硬性约定同样来自 AGENTS.mdTypeScript strict 模式、避免any、注释使用英文跨平台路径用pathe而非node:path通用可复用组件放在packages/internal/components应用专属 UI 留在各自 app 内测试用 Vitest 并与源码同目录。四、社区与许可证社区交流渠道官方 Discord 与 Twitter/Xfolo_is用于讨论想法、提问和分享贡献。许可证根据 CONTRIBUTING.md 与根 package.jsonlicense: AGPL-3.0-only向 Folo 提交代码即表示同意其贡献以GNU Affero General Public License v3授权发布特殊例外条款见 README.md。五、贡献流程速查清单corepack enable corepack prepare准备包管理器环境pnpm install安装依赖postinstall 会自动构建所有内部包按改动目标选择开发入口改 Web/渲染层cd apps/desktop pnpm run dev:web通过线上__debug_proxy页面调试改 Electron 主进程/桌面能力cp .env.example .env、设置VITE_API_URL后pnpm run dev:electron改分享页 SSRcd apps/ssr pnpm run dev改移动端配置EXPO_PUBLIC_APP_CHECK_DEBUG_TOKENpnpm run ios一次pnpm run dev改原生模块则进apps/mobile/ios用 Xcode 编译FollowNative提交前按固定顺序通过门禁pnpm run typecheck→pnpm run lint:fix→pnpm run test保持提交信息清晰、附测试、更新文档并遵守 AGPL-3.0 授权约定。【免费下载链接】follow Folo is the AI RSS Reader项目地址: https://gitcode.com/GitHub_Trending/fol/follow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Folo（follow）开源贡献指南：从 Corepack 环境准备到四端开发工作流与质量门禁
Folofollow开源贡献指南从 Corepack 环境准备到四端开发工作流与质量门禁【免费下载链接】follow Folo is the AI RSS Reader项目地址: https://gitcode.com/GitHub_Trending/fol/follow本文基于 FoloAI RSS 阅读器仓库follow的官方贡献文档 CONTRIBUTING.md 编写覆盖从 Corepack pnpm 环境准备、四种开发入口浏览器 / Electron / 外部 SSR / 移动端的完整操作步骤到提交前必须通过的质量门禁typecheck → lint → test。读完本篇你可以独立把该 monorepo 跑起来并对每一步命令背后的实现如__debug_proxy在线调试机制、移动端的 App Check 调试令牌有源码级的理解具备直接向该项目提交代码的基础。一、准备工作monorepo 结构与包管理器Folo 是一个由pnpm workspaces Turbo管理的 monorepo。在动手前需要先理解仓库的组织方式这决定了后续每条命令的作用范围根工作区定义在 pnpm-workspace.yaml包含apps/*、packages/**/*、apps/desktop/layer/*以及apps/mobile/web-app/html-renderer并排除了**/example目录四个主要应用分别是 apps/desktopElectron 桌面端Vite React 渲染层、apps/mobileExpo / React Native 移动端、apps/ssr用于外部分享的极简 SSR 站点、apps/landing落地页共享逻辑沉淀在packages/internal/*components、store、hooks、database 等。启用 Corepack官方要求贡献者先启用 Corepack 中声明的packageManager字段当前仓库锁定为pnpm10.17.0自动匹配正确的 pnpm 版本避免团队内包管理器版本漂移corepack enable corepack prepare从源码结构看这一机制被双重加固根package.json的prepare脚本为simple-git-hooks corepack prepare即pnpm install后会自动再次执行corepack prepare确保锁定的 pnpm 版本与 git hooks 同步就绪。安装依赖pnpm install需要注意 package.json 中配置了postinstall钩子postinstall: pnpm run build:packages, build:packages: turbo run build --filter\./packages/**/*\也就是说安装依赖的同时会用 Turbo 把所有packages/**下的内部包预先构建一遍。这也解释了为什么 AGENTS.md 中给出的Setup commands以pnpm install作为第一条——安装命令本身就是环境准备的一部分首次安装耗时会明显长于后续安装。二、四种开发入口CONTRIBUTING.md 提供了四条开发路径浏览器、Electron、外部 SSR Web、移动端。下面逐一展开并给出源码层面的佐证。2.1 浏览器开发推荐__debug_proxy调试入口官方推荐在浏览器中开发因为它体验更轻、更接近最终 Web 形态cd apps/desktop pnpm run dev:web该命令的实际定义在 apps/desktop/package.json 中dev:web: cross-env WEB_BUILD1 viteWEB_BUILD1标记这是一个纯 Web 构建不带 Electron 主进程。文档说明启动后会引导你访问https://app.folo.is/__debug_proxy从而复用线上 API 环境进行开发调试。这个__debug_proxy机制在源码中可以直接验证桌面端的 vite.config.ts 在构建时会把调试页写出到dist/__debug_proxy.html与dist/__debug_proxy/index.html并在开发模式打印两条调试地址——生产调试页https://app.folo.is/__debug_proxy.html与开发调试页https://dev.folo.is/__debug_proxy.html部署侧vercel.json 配置了重写规则把/__debug_proxy与/__debug_proxy/:path*请求统一落到__debug_proxy.html保证线上路径可用路由侧apps/desktop/layer/renderer/src/router.web.tsx 通过globalThis[__DEBUG_PROXY__]或 pathname 前缀/__debug_proxy判断是否处于调试代理运行时此时改用createHashRouter因为线上页面并非部署在站点根路径下hash 路由可避免刷新 404。也就是说本地 Vite dev server 提供 JS 资源线上__debug_proxy页面提供 API 与域名环境二者结合即构成浏览器里开发、打线上后端的完整链路。2.2 Electron 开发若需要在桌面壳内开发CONTRIBUTING.md 给出的步骤为# 0. 进入目录 cd apps/desktop # 1. 复制示例环境变量文件 cp .env.example .env # 2. 将 .env 中的 VITE_API_URL 设置为 https://api.follow.is # 3. 启动开发服务器 pnpm run dev:electrondev:electron实际执行的是electron-vite dev见 apps/desktop/package.json即同时启动 Electron 主进程与渲染进程。关于.env文件仓库内已提供 apps/desktop/.env.example包含以下变量变量示例值说明VITE_WEB_URLhttp://localhost:5173本地 Web 渲染地址VITE_API_URLhttp://localhost:3000API 后端地址文档要求改为https://api.follow.isVITE_IMGPROXY_URLhttp://localhost:2873图片代理地址VITE_SENTRY_DSN空错误上报 DSNVITE_BUILD_TYPEproduction构建类型VITE_INBOXES_EMAILfollow.re收件箱邮箱VITE_PUBLIC_POSTHOG_KEY/VITE_PUBLIC_POSTHOG_HOST空埋点配置文档中的排障提示如果遇到登录问题可以把浏览器 Cookie 里的__Secure-better-auth.session_token复制到应用中复用已有的浏览器会话完成登录态。2.3 外部 SSR Web 应用开发SSR 站点对应 apps/ssr 目录用于外部分享场景例如分享内容页的服务端渲染版本。启动方式最简单cd apps/ssr pnpm run dev另外根 package.json 还提供了一条dev:web脚本turbo run follow/web#dev follow/ssr#dev可并行拉起 desktop 渲染端与 SSR 端适合需要两侧同时联动的改动。2.4 移动端开发需要 MacCONTRIBUTING.md 明确标注移动端开发需要Mac 设备并已安装 Xcode 及相应依赖。步骤如下# 1. 进入目录 cd apps/mobile # 2. 复制环境变量文件并写入调试令牌 cp .env.example .env echo EXPO_PUBLIC_APP_CHECK_DEBUG_TOKENxxx .env # 也可以手动在 .env 中添加 EXPO_PUBLIC_APP_CHECK_DEBUG_TOKENxxx # 注意令牌值可以是任意字符串 # 3. 从源码构建并安装 Folo(dev) 应用耗时较长只需做一次 pnpm expo prebuild --clean # 可选 pnpm run ios # 4. 启动开发服务器 pnpm run devEXPO_PUBLIC_APP_CHECK_DEBUG_TOKEN并不是随意要求——从源码 apps/mobile/src/initialize/app-check.ts 可以看到它的用途provider.configure({ apple: { provider: __DEV__ ? debug : appAttest, debugToken: env.APP_CHECK_DEBUG_TOKEN, }, android: { provider: __DEV__ ? debug : playIntegrity, debugToken: env.APP_CHECK_DEBUG_TOKEN, }, isTokenAutoRefreshEnabled: true, })即开发态__DEV__下 Firebase App Check 使用debugprovider 并注入该调试令牌生产态则切换为 iOS 的appAttest/ Android 的playIntegrity。这就是为什么该令牌值可以是任意字符串它在 debug provider 下由开发者自行生成并配置到 Firebase 控制台即可。仓库中的 apps/mobile/.env.example 也同时预留了SENTRY_AUTH_TOKEN变量位。开发 iOS 原生模块需要修改FollowNative原生模块时对应 apps/mobile/native 下的 Expo 原生模块按文档操作# 1. 进入 iOS 工程目录 cd apps/mobile/ios # 2. 在 Xcode 中打开工作区 open Folo.xcworkspace # 3. 在左侧 Pods 目录中选择 FollowNative 后直接 Build Run原生模块本身是一个 Expo module见 apps/mobile/native/expo-module.config.jsonnative/ios下包含 Swift 实现通过 CocoaPods 以FollowNative名义接入工程因此改动后需在 Xcode 中重新编译 Pods 才会生效。三、质量门禁与代码规范CONTRIBUTING.md 的 Contribution Guidelines 要求代码遵循项目编码规范、提交信息清晰简洁、为改动附带相关测试、按需更新文档。落到可执行层面AGENTS.md 给出了明确的提交前必过质量门禁并且顺序是固定的# 1) 先跑类型检查必须 pnpm run typecheck # 2) 再跑 Lint 并自动修复 pnpm run lint:fix # 3) 最后跑测试 pnpm run test对应的根 package.json 脚本值得细看typecheck: turbo typecheck, lint: pnpm run lint:tsl eslint, lint:fix: eslint --fix, lint:tsl: tsslint --project apps/*/tsconfig.json, test: cross-env CI1 pnpm --recursive run test即 lint 实际包含两层tsslint基于 ts 项目的类型级 lint作用于所有 app 的 tsconfig加eslint测试则以CI1递归执行各包的测试测试框架为 Vitest测试文件与源码就近放置如 apps/cli/src/args.test.ts 这类同名*.test.ts文件。此外仓库还配了自动化护栏提交时会额外触发simple-git-hooks的 pre-commit 钩子执行pnpm exec lint-stagedlint-staged对暂存文件统一执行eslint --fix与prettier --write并对locales/**/*.json额外运行dedupe:locales即eslint --fix locales/**保持多语言词条排序一致对apps/mobile/src/**触发构建号自增脚本。代码风格上的硬性约定同样来自 AGENTS.mdTypeScript strict 模式、避免any、注释使用英文跨平台路径用pathe而非node:path通用可复用组件放在packages/internal/components应用专属 UI 留在各自 app 内测试用 Vitest 并与源码同目录。四、社区与许可证社区交流渠道官方 Discord 与 Twitter/Xfolo_is用于讨论想法、提问和分享贡献。许可证根据 CONTRIBUTING.md 与根 package.jsonlicense: AGPL-3.0-only向 Folo 提交代码即表示同意其贡献以GNU Affero General Public License v3授权发布特殊例外条款见 README.md。五、贡献流程速查清单corepack enable corepack prepare准备包管理器环境pnpm install安装依赖postinstall 会自动构建所有内部包按改动目标选择开发入口改 Web/渲染层cd apps/desktop pnpm run dev:web通过线上__debug_proxy页面调试改 Electron 主进程/桌面能力cp .env.example .env、设置VITE_API_URL后pnpm run dev:electron改分享页 SSRcd apps/ssr pnpm run dev改移动端配置EXPO_PUBLIC_APP_CHECK_DEBUG_TOKENpnpm run ios一次pnpm run dev改原生模块则进apps/mobile/ios用 Xcode 编译FollowNative提交前按固定顺序通过门禁pnpm run typecheck→pnpm run lint:fix→pnpm run test保持提交信息清晰、附测试、更新文档并遵守 AGPL-3.0 授权约定。【免费下载链接】follow Folo is the AI RSS Reader项目地址: https://gitcode.com/GitHub_Trending/fol/follow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
