如何为 smc.peering.tw 贡献代码:开发环境搭建与PR流程完整清单
如何为 smc.peering.tw 贡献代码:开发环境搭建与PR流程完整清单
smc.peering.tw(台灣海纜動態地圖)是一个基于 React + TypeScript + Vite 构建的开源项目,用交互式地图展示连接台湾与世界的海底光缆实时状态与历史故障事件。想参与贡献?本文提供一份开发环境搭建与 PR 流程完整清单,帮助你快速上手贡献代码。
项目简介:这是一个什么项目
在开始贡献之前,先快速了解一下项目结构,有助于你定位要改的代码:
- 技术栈:React 19、TypeScript 5.9、Vite 8、Tailwind CSS 4,详见 package.json
- 地图渲染:使用 Maplibre GL 绘制海缆路由,核心实现在 src/components/Map.tsx
- 多语言支持:通过 i18next 实现英文与繁体中文切换,词条位于 src/i18n/locales/
- 数据格式:海缆、登陆点、故障事件等静态 JSON 数据放在
src/data/目录,完整数据格式说明见 README.md
开发环境搭建:从克隆到本地运行
1. 环境要求(前置清单)
| 依赖 | 版本要求 | 说明 |
|---|---|---|
| Node.js | ≥ 18 | 运行 Vite 开发服务器 |
| npm / yarn | 最新版 | 安装依赖 |
| Python 3 | ≥ 3.9(可选) | 运行数据转换脚本时使用 |
2. 克隆仓库
git clone https://gitcode.com/gh_mirrors/sm/smc.peering.tw
cd smc.peering.tw
3. 安装依赖
npm install
4. 准备本地数据文件
项目运行依赖三个数据文件,本地开发时可以这样处理:
src/data/landing-points.json:填入[]即可src/data/incidents.json:运行 convert_incidents.py 脚本生成(需要安装 requirements.txt 中的requests、pytz)src/data/cables/*.json:目录留空也能运行
💡 这些 JSON 的字段格式(如
status、cableid、segment)在 README.md 的 Data Format 一节有完整示例,修改故障数据结构时务必对照。
5. 启动开发服务器
npm run dev
打开浏览器访问 http://localhost:5173,看到海缆地图即搭建成功。开发服务器的代理规则定义在 vite.config.ts,@ 路径别名也在这里配置。
代码风格规范:提交前必须通过 Lint
项目使用 ESLint 9 的 Flat Config 进行代码检查,配置位于 eslint.config.ts。几个关键规则:
- 启用
typescript-eslint的类型检查规则(recommendedTypeChecked) - 强制分号(
semi: true)、箭头函数括号(arrowParens: true) - 导入顺序规则
import-x/order:内置模块 → 外部包 → 内部模块 → 相对路径,组间必须空行
提交前运行:
npm run lint
另外 npm run build 会先执行 tsc -b 做全量类型检查,因此类型错误会直接阻断构建,PR 前建议本地跑一遍。
常用 npm 脚本速查
| 命令 | 用途 |
|---|---|
npm run dev |
启动开发服务器(监听 0.0.0.0) |
npm run build |
类型检查 + 构建生产包(输出到 dist) |
npm run preview |
本地预览生产构建 |
npm run lint |
运行 ESLint 检查 |
PR 流程完整清单:从分支到合并
按照 README.md 中 Contributing 一节的标准流程,贡献 PR 共 5 步:
- Fork 仓库:先 Fork 到自己名下
- 创建功能分支:
git checkout -b feature/amazing-feature(分支名建议feature/、fix/等前缀) - 提交改动:
git commit -m 'Add some amazing feature',提交信息用祈使句简述改动 - 推送分支:
git push origin feature/amazing-feature - 发起 Pull Request:在 PR 描述中说明改动动机、影响范围,最好附截图
提交 PR 前的自检清单
- [ ]
npm run lint无 error - [ ]
npm run build成功通过(类型检查 + 构建) - [ ] 移动端布局未破坏(项目支持桌面、平板、手机三种断点)
- ] 涉及界面文案时,同步更新 [src/i18n/locales/en.json 与 src/i18n/locales/zh-tw.json 两套语言文件
- [ ] 版本信息:项目会在 README.md 的 Version History 中记录每个版本变更,按惯例补充说明
新手友好:从哪类改动入手最容易
🌱 第一次贡献建议从这些低风险改动开始:
- 文案修正:i18n 语言文件中的错别字或翻译优化,只动 JSON 不动逻辑
- UI 微调:src/components/ui/ 下的按钮、弹窗等通用组件
- 图例与时间轴:src/components/MapLegend.tsx、src/components/dialog/Timeline.tsx 等展示层组件
- 地图交互:src/components/Map.tsx 中的 Popup 文案与展示逻辑
常见问题(FAQ)
Q: npm run dev 报找不到数据文件?
A: 确认第 4 步的三个 JSON 文件都已按最小配置创建,尤其是 src/data/landing-points.json 至少要是 []。
Q: 类型检查报错,但不确定哪里错了?
A: 运行 npm run build 查看 tsc -b 的完整错误输出,报错位置会精确到行号。
Q: 想改地图配色或图层?
A: 地图样式定义在 src/components/Map.tsx 的 BASE_MAP_STYLE 中,海缆分段取色逻辑在 src/lib/cable-status.ts,改动前建议先阅读 README.md 中 Data Format 部分理解数据结构。
总结
为 smc.peering.tw 贡献代码的完整路径:搭建环境(Node ≥ 18 + npm install)→ 准备最小数据文件 → npm run dev 本地验证 → npm run lint 与 npm run build 双检查 → 按 Fork/分支/PR 五步流程提交。照着这份清单走,你的第一个 PR 就能顺利发出。项目基于 LICENSE 的 MIT 协议开源,欢迎参与!
