本文面向新手，讲解开源项目run-abroad（润学导航）的完整贡献流程：在 js/data.js 的PATHWAYS数组里按规范新增一条签证 / 移民路径，再用浏览器控制台里的validatePathways()自动自检，确保数据无误后提交。无需安装任何依赖，克隆仓库、改一行数据、刷新页面即可看到效果。

一、先了解项目结构：为什么改一个文件就够了

run-abroad 是一个纯静态、零依赖的决策工具：填 10 项基本信息，从 72 条签证 / 移民路径中筛出适合你的，并告诉你还差什么。所有计算都在浏览器里完成，没有后端。

项目刻意不做模块化和打包，三个核心 JS 文件按顺序用<script>引入（见 index.html 底部）：

官方字段规范全部写在 CONTRIBUTING.md 里，本文是它的可视化补充。

二、一键克隆与本地预览

仓库是只读的，克隆到本地（fork 后再修改）：

git clone https://gitcode.com/gh_mirrors/ru/run-abroad cd run-abroad

没有构建步骤、没有 npm。直接双击 index.html 打开，或起个本地服务器：

python3 -m http.server 8000 # 浏览器访问 http://localhost:8000

💡 小提示：部分浏览器在file://下控制台告警会多一些，建议统一用本地服务器预览。

三、读懂路径数据结构：js/data.js 长什么样

打开 js/data.js，核心就是 PATHWAYS 数组——每条路径一个对象。以新西兰打工度假签证为例（js/data.js#L211-L224）：

{ id: 'nz-whv', country: '新西兰', flag: '🇳🇿', name: '打工度假签证 (WHV)', nameEn: 'Working Holiday Visa', type: 'workholiday', duration: '12 个月', pr: '本身不通往永居，但可在境内转学签或技术工签', req: { age: [18, 30], minDeg: DEG.highschool, minEng: ENG.ielts55, fundsUSD: 3000 }, quota: '中国大陆每年 1000 个名额，开放即秒光', cost: '签证费约 NZ$470 + 机票 + 押金资金证明', difficulty: 3, notes: '门槛最低的一条「先出去」路线……', official: '政府官网链接', }

理解数据前，先认识文件头部的等级编码（js/data.js#L13-L14），门槛字段都引用它们而不是写死文字：

req 门槛字段速查

req里的字段全是门槛，留空 = 无此要求（js/data.js#L202-L208）：

type必须在 TYPE_LABEL 中已定义，共 10 种：workholiday（打工度假）、jobseek（毕业生找工作签）、talent（人才引进）、skilled（技术移民）、work（工作签证）、study（留学转移民）、vocational（职业教育）、nomad（数字游民）、invest（创业 / 投资）、soft（软着陆 / 落脚点）。

四、新增签证路径的完整步骤

⚠️ 最重要的一条规则：没有政府官网来源的修改无法合并。动手前先找到该签证的官方页面。

第 1 步：确定插入位置。PATHWAYS数组按类型分区（如 打工度假区、毕业生找工作签区 js/data.js#L268），把新对象加进同类型分区里，方便维护。

第 2 步：复制一个相近的路径对象作模板，逐字段改写。注意三个必填项：

• id：唯一，命名惯例为「国家代码 + 简称」，如nz-whv、uk-hpi
• official：必须是政府官网链接
• notes：写别处查不到的实操信息，不要复述门槛

第 3 步：如果新路径涉及一个新国家，别漏掉两处同步（自检也会检查）：

1. 在 REGION_OF 里把国家归入地区（asia/eu/na/oc/latam/other）
2. 在 INCOME_SOURCE_LOCATIONS 里补充该国家名

第 4 步（可选）：补充详情页深度内容。部分路径带有detail字段（参考 EB-5 的写法），包含timeline、steps（办理步骤）、docs（材料清单）、pitfalls（坑）和links，由 js/detail.js 渲染到 pathway.html。这是最有价值的加分项。

写 notes 的原则：写实操，不复述门槛

CONTRIBUTING.md 给出的标准：

• ✅ 「近年因申请量暴增设置了年度处理上限，等待期显著变长，市面上大量『包过』中介风险很高」
• ❌ 「这是一个适合年轻人的好签证」（没有信息量）

请用自己的话总结，不要大段复制官网原文。

五、validatePathways 自动自检：提交前最后一道关

打开 index.html，按F12查看控制台。validatePathways()会在页面加载时自动运行（js/app.js#L631-L636），结果以[数据校验]前缀打印告警——如果新路径一切正常，控制台是干净的，什么都没有。

这个函数的完整逻辑在 js/data.js#L1373-L1393，它检查 5 类问题：

💡 在控制台里还能直接手动复查：输入validatePathways()回车，返回值就是问题列表数组，空数组[]表示全部通过。

六、手动验证：别漏写门槛

自检只查数据完整性，查不出逻辑错误。提交前还要做人工测试：

1. 在表单里填几组不同的条件（如年轻 / 高学历 / 强语言，与年长 / 低学历 / 无语言）
2. 确认新路径出现在合理的分档里（符合条件 / 差一点 / 需要长期准备 / 暂时走不通）
3. 重点确认：新路径不会对所有人都显示「符合条件」——这通常意味着req里漏写了某个门槛

另外别忘了刷新后页面右上角的路径总数（js/app.js#L636 渲染的#total）应比原来多 1。

七、常见坑清单

结语：你的第一条贡献可以很简单

整个流程只有三步：克隆仓库 → 在 js/data.js 里照模板加一个对象 → 打开页面看控制台。零依赖的设计意味着改一行数据、刷新页面就能看到效果。如果你发现某条路径的数据已经过时（移民政策变动极快），提 Issue 并附上官网链接，同样是最高价值的贡献。

更多规范细节见 CONTRIBUTING.md，项目基于 MIT License，数据和代码都可自由使用。