桌面应用【免费下载链接】VortexVortex Development项目地址https://gitcode.com/gh_mirrors/vor/Vortex点击查看免费下载本篇指南以 CONTRIBUTING.md 为骨架系统讲解如何为 Vortex 提交代码包括当前维护团队对 PR 规模的硬性约束与 AI 辅助贡献要求、从零搭建开发环境的分步流程、pnpm run verify/build/start/dev等核心命令的底层实现、热重载与 VS Code 调试技巧以及本地打包与分支发布策略。读完你将掌握一套可直接上手的 Vortex 贡献实战流程并理解其背后基于 pnpm Nx Electron 的工程化设计。一、先说结论当前只接受小 PR在动手写任何代码之前请先读完 CONTRIBUTING.md 开头那条醒目的[!IMPORTANT]提示当前阶段只接受小规模 Pull Request。原因很直接——Vortex 正经历大规模的基础架构重构large foundational changes维护团队没有足够的评审产能同时处理大贡献与重构工作。如果你现在提交一个大 PR它大概率会一直处于未评审状态直到与底层代码脱节而被迫关闭。这条规则针对的是团队的评审产能而不是你贡献的质量。文档也明确表示团队正在招聘、状况会变化。什么算“小”文档给出了一个粗略的量化标准改动不超过 400 行、涉及文件不超过 10 个忽略 lockfile、生成文件与大规模重命名的 PR可以不经过前期沟通直接评审。但这并非硬性上限判断标准其实是影响半径blast radius而非行数一个 500 行的改动如果是一个自包含的修复并配有测试可以接受一个 200 行的改动如果牵动六个扩展大概率不行——因为评审成本在于它波及多少子系统而不在于行数本身。如果你的改动超出上述规模、或跨越多个扩展文档强烈建议先写 feature request或在 Discord 上先与维护者沟通方案并等待对方认可后再动手。开写之前花几分钟对话能避免你投入大量时间写出一份无法合并的东西。二、Pull Request 提交规范CONTRIBUTING.md 对 PR 本身提出了三条硬性要求一个 PR 只做一件逻辑上的事。如果 PR 描述里需要出现 and 这个词那它大概率应该拆成两个 PR。关联它修复的 issueLink the issue it fixes。说明你测试了什么、在哪个平台上测试的Say what you tested and on which platform。开 PR 之前必须运行pnpm run verify。这一步覆盖格式检查formatting、lint、类型检查typecheck、构建build与测试test。值得注意的是与既有已规划/进行中的工作冲突、不符合架构、或大到团队无法评审的 PR会被直接关闭——文档强调“这不是对代码质量的评判”。verify 命令到底做了什么查看仓库根目录的 package.jsonverify的实际定义是一条命令链pnpm run format pnpm run build pnpm run test其中format→pnpm oxfmt格式统一交给 oxfmt包括 Markdown 在内build→pnpm nx run-many -t build lint typecheck pnpm run assetsNx 并行跑所有子项目的 build/lint/typecheck再生成依赖报告资产test→pnpm nx run-many -t test test:integration --exclude vortex/e2e注意verify 刻意排除了 E2E 套件因为vortex/e2e需要打包好的应用和真实游戏安装见 AGENTS.md 的 Verification 一节。另外AGENTS.md 还给出了一个容易被忽略的警告不要在 dev 会话pnpm run dev或 VS Code Debug Electron 运行中期间运行verify。因为 verify 的 build 步骤会把生产产物写入src/main/build——这正是运行中的应用加载的目录会覆盖tailwind:watch生成的 CSS 并替换 HMR 渲染器 bundle导致样式损坏、HMR 失效直到重启 dev。dev 会话期间请改用不写该目录的检查pnpm run typecheck、pnpm run lint以及从所属项目目录内执行pnpm exec vitest run file跑单个测试。三、AI 辅助贡献工具随意责任在你Vortex 对 AI 生成的代码持开放但严格的态度你可以使用任何工具但必须满足同一个要求——你是作者你必须理解你提交的每一行代码。落实到实践中这意味着你需要能够解释为什么改动这样写、已经实际运行过它、并且通读了 diff。如果评审者就 PR 中的某个决策提问回答这是模型生成的thats what the model produced不算答案。团队会直接关闭大规模机器生成的 PR 而不做详细评审——没有人有产能去审计两边都没读过的成千上万行代码前述规模规则与代码由谁生成无关。因此在使用 AI 辅助时务必把改动控制在小 PR范围内并逐行理解后再提交。文档推荐的编辑器是 VS Code首次打开仓库时会提示安装工作区扩展。四、环境要求与 Setup从零开始搭建开发环境开始之前请确认具备以下基础条件用于创建 PR 的GitHub 账号gitCLI 或 Git GUI 客户端如 GitHub Desktop支持 TypeScript 的编辑器VS Code、WebStorm 或 Neovim。仓库采用pnpm workspace Nx的 monorepo 结构见 pnpm-workspace.yaml根级 package.json 声明packageManager: pnpm11.10.0engines/devEngines固定 Node.js 24.20.0。pnpm 是唯一需要手动安装的工具——仓库会在安装时自动切换到它锁定的 pnpm 版本并下载固定的 Node.js 运行时无需版本管理器。4.1 按发行版安装前置依赖CONTRIBUTING.md 的 Setup 一节按平台拆分了前置依赖文档需要先安装系统级依赖再进入共享安装流程平台依赖要点对应文档WindowsVS 2022 Build Tools含 C 桌面开发工作负载、MSVC v143、ATL/MFC、Windows 11 SDK、Git、Python 3.14、CMake、.NET 9 SDKdocs/install-instructions/windows.mdArch / CachyOS / Manjarobase-devel git python python-setuptools dotnet-sdk-9.0docs/install-instructions/archlinux.mdDebian / Ubuntu / Pop!_OS / Linux Mintbuild-essential git python3 python3-setuptools curl wget libfontconfig-dev .NET 9 SDKdocs/install-instructions/debian-based.mdFedoradevelopment-tools组包 git python3 python3-setuptools dotnet-sdk-9.0 gcc g fontconfig-develdocs/install-instructions/fedora.mdNixOS用 flake 提供全部依赖含 pnpm/node替代手动安装 pnpmdocs/install-instructions/nixos.md其他发行版.NET 9 SDK Python 3.12需 setuptools C/C 工具链docs/install-instructions/generic.md几个值得注意的细节均来自对应安装文档Windows上官方推荐把仓库克隆到C:\v以规避 Windows 路径长度限制Vortex 依赖原生 Node 模块node-gyp编译需要 ATL、MFC 与 Windows 11 SDK所以Desktop development with C默认工作负载不够用必须按文档补选 Individual Components。NixOS用户不需要手动安装 pnpmdirenv allow之后由仓库 dev shell 提供但要注意在仓库外启动 Git GUI 客户端如 GitKraken时pre-commit 钩子可能因找不到pnpm而失败。Generic指南特别强调 Python 3.12 需要额外安装setuptools。4.2 共享安装流程Shared Setup完成发行版前置依赖后进入 docs/install-instructions/shared.md 描述的共享流程Linuxgit clone --recurse-submodules https://github.com/Nexus-Mods/Vortex.git cd Vortex curl -fsSL https://get.pnpm.io/install.sh | sh - # 安装 pnpm pnpm install # 安装依赖WindowsPowerShellgit clone --recurse-submodules https://github.com/Nexus-Mods/Vortex.git C:\v cd C:\v winget install -e --id pnpm.pnpm pnpm install关于pnpm install的机制shared.md 解释得很清楚步骤 2 安装的 pnpm 只负责引导流程真正安装时 pnpm 会读取package.json里的packageManager字段自动切换到精确版本再按devEngines.runtime下载锁定的 Node.js——编译原生模块是这一步最耗时的部分。pnpm install还会自动安装 git pre-commit 钩子用于自动格式化。如果钩子缺失可手动执行pnpm run prepare根级prepare: huskyhook 配置见 package.json 的lint-staged对每个暂存文件运行pnpm exec oxfmt。安装完成后可用以下命令验证环境来自 shared.md 的 Verify Setupgit --version pnpm --version pnpm exec node --version # 报告仓库锁定的 node 版本未必等于 PATH 上的版本 pnpm nx --version python3 --version dotnet --list-sdks五、Developing构建与启动Setup 完成后日常开发循环就两行命令pnpm run build # 全量构建 pnpm run start # 启动 Electron 应用根级build通过 Nx 并行执行所有子项目的build lint typecheck随后运行assets脚本生成依赖报告见 package.jsonstart实际是pnpm nx run vortex/main:start而vortex/main的 start 目标是pnpm electron .src/main/package.json即从主进程构建产物build/main.cjs启动 Electron。关于格式化务必有心理准备pre-commit 钩子会对每个暂存文件含 Markdown重写oxfmt格式所以你会看到自己的格式被改写。想避免这种惊扰先手动跑一遍pnpm run format钩子就变成 no-op 了。另外钩子可能在提交中途触发依赖安装因此一次 commit 有时会耗时约 30 秒并打印安装输出这是正常现象。六、Hot Reload用pnpm run dev迭代 UI针对渲染进程renderer / UI代码的迭代pnpm run dev可以完全绕开 build/start 的循环——它启动 webpack 与 Tailwind 的 watch 模式并以热模块替换HMR方式启动 Electron见 CONTRIBUTING.md 的 Hot reload 一节。dev的实际组成可以从 nx 配置还原出来根级dev→pnpm nx run vortex/main:dev而vortex/main的dev目标continuous、cache 关闭依赖两条 watch 流水线vortex/stylesheets的tailwind:watchTailwind CSS 增量编译vortex/renderer的watch其 executor 为pnpm -F vortex/renderer exec node ./dev.mjs见 src/renderer/package.json。renderer 的 dev.mjs 源码揭示了底层机制它以WEBPACK_WATCH: true调用 webpack watch首次编译成功后才 spawnpnpm -F vortex/main run start启动 Electron并在每次编译结束时打印[vortex-hmr] finished after Nms: hash同时会清理src/main/build下残留的*.hot-update.*文件。各类型改动的热更新行为改动类型行为组件.tsx通过 react-refresh 原地热替换React 与 Redux 状态保留无需重载无法热应用的改动reducers、utils、扩展index.ts初始化代码自动触发一次干净的窗口重载Tailwind class 变更重建tailwind-v4.css并原地换样式表无需重载主进程src/main、preload、vortex/shared不受 HMR 覆盖需要重启pnpm run devextensions/与extensions/games/下的动态扩展不受 HMR 覆盖需要重新启动应用主进程侧的佐证也在源码里MainWindow.ts的will-navigate处理器对当前页面的导航即 HMR 回退触发的页面刷新见 MainWindow.ts 中引用的tools/hmr-client.cjs做了放行判断说明 HMR 的回退重载走的是页面级 reload。七、DebuggingVS Code 调试CONTRIBUTING.md 给出的调试要点非常简洁F5同时调试主进程与渲染进程调试前先pnpm run build保证 source map 是最新的。详细的调试手册在 docs/DEBUGGING-GUIDE.md这里提炼几个与贡献流程直接相关的关键点7.1 调试配置.vscode/launch.json默认的Debug Electronprofile 是一个 compound同时启动Debug Main Process以NODE_ENVdevelopment、START_DEVTOOLStrue、--remote-debugging-port9222启动 ElectronDebug Renderer Processattach 到 9222 端口上的渲染进程。其余可用 profile 包括 Debug Main Process单独调试主进程适合启动流程、IPC、文件系统、更新器、Debug Renderer Process先启动主进程再 attach、Debug Jest Tests以及为 NixOS 等需要系统 Electron 的环境准备的 System Electron 系列和用于测试发布更新的 Staging 系列设置VORTEX_DEV_UPDATER1与VORTEX_UPDATER_REPO。7.2 断点与常见坑主进程断点建议下在 src/main/src/main.ts 及src/main/src/*.ts渲染进程断点下在 src/renderer/src/renderer.tsx、src/renderer/src/views/*.tsx、src/renderer/src/extensions/**/*.ts。热替换过的代码会让基于行的断点失效直到下一次完整重载——如果断点不触发了按 CtrlR 重载窗口。断点打不中的通用排查顺序重建pnpm run build→ 确认src/main/build/下有最新产物 → 核对 launch.json 的outFiles与构建输出匹配 → 重启 VS Code 清断点缓存。7.3 诊断环境变量DEBUGGING-GUIDE.md 汇总了一批在.env或启动 shell 中设置即可生效的诊断开关常用的有变量作用START_DEVTOOLStrue启动时自动打开 DevToolsMainWindow.ts中由isEnvSet(START_DEVTOOLS)触发见 MainWindow.tsVORTEX_ENABLE_LOGGING1在非NODE_ENVdevelopment构建中打开文件日志DEBUG_REACT_RENDERStrue阻止窗口 focus/blur 更新状态避免检查渲染时引入干扰HIGHLIGHT_I18Ntrue把所有翻译字符串大写并加TT:前缀让硬编码字符串一目了然VORTEX_DEV_UPDATER1VORTEX_UPDATER_REPO从源码运行更新器并指定它读取的仓库VORTEX_TRACE_DB_WRITES1为LevelPersist每次写入输出面包屑日志用于定位持久化队列挂起问题日志文件位置也有区分开发构建从源码运行写%appdata%/vortex/main/*.log生产构建写%appdata%/vortex/*.log日志级别为[DEBG]/[INFO]/[WARN]/[ERRO]。排查退出时无限挂起这类问题VORTEX_TRACE_DB_WRITES1是关键工具——最后一次没有对应exit的enter行就是卡住的那次调用相关阈值SLOW_WRITE_THRESHOLD_MS定义于 src/main/src/store/LevelPersist.ts。八、Packaging本地打包与发布管线8.1 本地构建未签名 Windows 安装包想要在本地验证生产行为如自动更新流程从仓库根目录运行pnpm package:nosign产物输出到根目录的dist/。签名安装包只由 CI 产出本地不要运行pnpm package签名变体。根级定义package.json显示两者都会先以NODE_ENVproduction跑完整 build再调用vortex/main的package:nosign。而 src/main/package.json 里的 pipeline 链条是publish清空dist、pnpm deploy物化独立包、prepare-dist-package.mjs解析catalog:/workspace:依赖→ electron-builder 从部署目录运行并输出到仓库根dist/。几个来自 docs/packaging/windows.md 的实操要点安装包内置的版本号来自src/main/package.json的占位符1.0.0打指定版本需先注入再还原pnpm -F vortex/main version 2.7.0 --no-git-tag-version --no-git-checks --allow-same-version pnpm package:nosign git restore src/main/package.json陷阱src/main内的package/package:nosign脚本单独运行会失败找不到部署目录它们依赖根级管线创建的 deploy 目录所以永远使用根级脚本。打包后建议运行 asar 校验脚本它会对比部署树中每个嵌套node_modules依赖版本与 asar 内实际版本不一致即报错node scripts/verify-packaged-asar.mjs产物包括vortex-setup-version.exeNSIS 安装器、.exe.blockmap差分自动更新、latest.yml更新器清单与win-unpacked/免安装目录。构建安装包的版本注入用pnpm -F vortex/main version ...注意该命令使用--no-git-tag-version等参数避免误提交。8.2 Flatpak 打包LinuxFlatpak 打包流程在 docs/packaging/flatpak.md注意文档顶部有[!WARNING]当前 Flatpak 构建暂时是坏的pnpm 支持待修复所以这条路径仅供了解。常用工作流脚本位于flatpak/scripts/会自动安装flatpak-node-generator依赖并补充 Flathub remote# 快速开发测试构建 运行 python3 flatpak/scripts/flatpak_build.py python3 flatpak/scripts/flatpak_run.py # 安装到本地仓库可出现在 KDE Discover / GNOME Software 中 python3 flatpak/scripts/flatpak_install.py python3 flatpak/scripts/flatpak_install.py --skip-build # 已构建过则跳过 # 生成 .flatpak 分发 bundle python3 flatpak/scripts/flatpak_bundle.py python3 flatpak/scripts/flatpak_bundle.py --skip-build首次构建前需初始化子模块git submodule update --init --recursive。九、FAQ我的改动何时进入 stable 版本CONTRIBUTING.md 的 FAQ 指向 docs/branching-and-release-strategy.md核心策略如下master 永远是最新代码是所有新工作的起点版本准备稳定时从 master 切出同名分支如v2.0该版本的 alpha/beta/stable 全部在此分支进行Bug 修复的流向同时影响 release 分支与 master 的 bug先在更相关的分支修再 cherry-pick 到另一边只影响单一分支的 bug 就地修复不确定时与团队确认停止 backport 的时机版本进入 stable、下一版本分支已切出后旧 release 分支进入维护模式此后只 backport 关键修复崩溃、数据丢失、安全标签与命名分支用版本名v2.0标签遵循 semverv2.0.0-alpha.1、v2.0.0-beta.1、v2.0.0补丁版本v2.0.1稳定版热修复直接在 release 分支上修复并打补丁标签不要创建单独的热修复分支。十、Further Reading继续深入仓库CONTRIBUTING.md 推荐了三个进一步阅读入口均已转换为仓库根目录相对路径所有文档索引——按主题组织的完整文档目录Vortex 的Start here建议先读 docs/repo-layout.md仓库布局与改某类东西从哪里开始的对照表与 docs/writing-documentation.md调试指南——VS Code 调试、日志文件、DevTools、Redux DevTools、性能排查Docker Dev Containers——docker/linux/Dockerfile.devcontainer 基于 Ubuntu 24.04内置 git、python3、.NET SDK 9.0fomod-installer 所需、Volta 等全部构建依赖可用于 VS Code Dev Containers 或 GitHub Codespaces。另外仓库根目录的 CODESTYLE.md 对代码风格提出了具体要求贡献前值得浏览例如行宽软限制 100 字符/硬限制 150、函数软限制 25 行、接口命名用I前缀、私有字段优先用#而非 TSprivate、错误信息中动态部分必须用引号包裹因为错误上报按消息与堆栈分组去重等。总结一份可执行的最小贡献清单综合全文一次符合规范的 Vortex 贡献可以归纳为六步控制规模改动 ≤400 行、≤10 文件单个逻辑变更超出范围先与维护者沟通方案搭建环境按发行版安装前置依赖Windows 见 windows.mdLinux 见对应发行版文档再执行共享流程shared.md本地开发pnpm run buildpnpm run start起步迭代 UI 用pnpm run dev享受热重载验证开 PR 前运行pnpm run verify覆盖 format/lint/typecheck/build/test且不含 E2Edev 会话期间改用 typecheck/lint/单测调试与打包VS Code 按 F5 双进程调试需要生产行为验证时用pnpm package:nosign提交描述里写明修复的 issue 与测试平台接受 pre-commit 钩子对格式的重写等待评审。若使用 AI 辅助生成代码请牢记文档的底线你必须理解提交的每一行并能解释任何评审问题——这与工具随意并不矛盾责任始终在作者这一侧。赞分享桌面应用【免费下载链接】VortexVortex Development项目地址https://gitcode.com/gh_mirrors/vor/Vortex点击查看免费下载相关推荐Popcorn Time开发者贡献指南Git工作流与PR规范Popcorn Time开发者贡献指南Git工作流与PR规范 作为开源项目Popcorn Time的贡献者遵循规范的Git工作流和Pull Request音视频Hypothesis 开发者贡献指南从测试编写到 PR 合并的完整工作流Hypothesis 开发者贡献指南从测试编写到 PR 合并的完整工作流 本文是 HypothesisPython 属性测试库仓库内开发者工作流指南的深度测试开发工具Langflow 贡献指南从 PR 规范到组件、Bundle 与模板的完整开发工作流Langflow 贡献指南从 PR 规范到组件、Bundle 与模板的完整开发工作流 Langflow 是一个用于构建和部署 AI Agent 与工作流的开源人工智能大模型AI AgentRAG后端前端MCP 服务工作流自动化上一篇Grasscutter命令生成器原神私服管理的完整解决方案下一篇终极指南如何用AutoLegalityMod插件为PKHeX节省90%手动验证时间创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考