你的第一个开源 PR 指南：Null Motion 本地开发环境、good first issue 清单与 PR 规范

Null Motion 是一个本地运行的动效广告拆解工具：把一支成品 motion-graphics 广告与它最初的 HyperFrames 黑白草稿逐帧对齐播放，并能一键将整段 breakdown 导出为 MP4。项目零依赖、npm start即可运行，是练习开源贡献的理想沙盒。本文带你在几分钟内搭好本地开发环境，找到适合新手的 good first issue，并掌握提交 PR 的规范，完成你的第一次开源贡献。

一、先认识 Null Motion：为什么它适合第一次贡献

Null Motion 的核心玩法是"成片在上，草稿在下"：

• 成片全宽循环播放，广告每一帧都在正片位置；
• 每个 section（Hook、Reveal、App、End card…）对应一张黑白 HyperFrames 草稿，只保留想法本身：文字、扁平形状、一个简单动作；
• 橙色播放头跟随正片逐帧移动，当前 section 的草稿会被高亮描边；
• 点击Download → Whole preview，即可用 WebCodecs 把整段拆解逐帧渲染并导出为 1920 宽、24 Mbps 的 MP4。

仓库自带 3 条参考片（Infinite、SaaS launch sequence、Motion study 08），首次运行无需任何配置即可播放。项目小到没有运行时依赖，改动一处立刻见效——这正是新手第一次贡献最需要的特性：反馈快、风险低。

二、本地开发环境搭建：零依赖的极简配置

环境要求一览

克隆并启动项目

git clone https://gitcode.com/gh_mirrors/nu/NullMotion cd NullMotion npm run dev # 打开 http://127.0.0.1:4343，改代码自动重启

注意两点：

• 没有npm install步骤——项目零依赖，克隆完直接跑；
• 开发模式用npm run dev（基于node --watch，改文件自动重启），正式发布模式是npm start。

端口被占用时可用环境变量切换，例如PORT=5000 npm start，或HOST=0.0.0.0 npm start允许局域网内其他设备访问。

项目关键目录速览

public/demo.html · demo.mjs · demo.css 预览页与 MP4 导出器（首页） public/drafts.mjs HyperFrames 草稿引擎（beat kinds） server.js · media.js 静态服务器、媒体流、音频抽取 scripts/ 导入、分镜规划、showcase 构建、检查 test/ Node 测试（node --test）

详细说明见 README.md 的 Project layout 一节，贡献须知集中在 CONTRIBUTING.md。

三、good first issue 清单：从哪儿开始动手

Null Motion 维护者在 README.md 中明确"we're looking for contributors"，issue 按标签分层：

• 🟢good first issue：小而聚焦，且会在 issue 里直接列出要改的文件，是第一次贡献的入口；
• 🙋help wanted：体量更大的需求，典型如新增 draft beat 类型（改 public/drafts.mjs）、导出选项、跨平台测试；
• 💡Discussions / Discord：超过 bug 修复量级的想法，先开 Discussion 对齐方向。

认领流程很简单：

1. 在目标 issue 下留言认领，避免两人做同一件事；
2. 一周内没有动静，认领自动释放；
3. 你的贡献按 MIT License 发布，每位贡献者都会写进 release notes。

新手优先选择"列出文件"的 good first issue，例如修改某个 beat 的排版、修一处文案、补一个 test/ 下的测试用例——改动范围小，评审快。

四、PR 规范：提交前必过的检查清单

提交前两条命令

npm test # node --test，跑全部测试 npm run check # 语法检查所有 UI 文件，并拦截硬编码的本地 companion URL

两条都绿了再开 PR，这是 CONTRIBUTING.md 的硬性要求。

PR 规范要点

• 小而聚焦：一个 PR 只做一个修复或一个功能；
• 真实浏览器验证 UI：在窄屏和宽屏各看一遍，并附截图或 GIF；
• 不加运行时依赖、不加 API key、不请求其他域名——浏览器只与本项目自己的服务器通信（server.js 是唯一的后端）；
• 不要提交参考片：导入的媒体放在被 Git 忽略的.local-media/与public/references/，showcase/只保留官方发布的 3 条参考；
• UI 状态要诚实：generation、渲染服务、Premiere 在本仓库中均未接入（服务端会返回501 NOT_CONNECTED），不要把未连接的功能显示成"可用"；
• 保留 THIRD_PARTY_NOTICES.md 中的第三方版权说明（GSAP、mp4-muxer）。

PR 会在两三天内被评审，保持 issue 沟通畅通即可。

五、常见本地问题速查

完整 FAQ 见 README.md 的 FAQ and troubleshooting 章节。

结语

Null Motion 用"零依赖 + 小而聚焦的 issue + 明确的检查命令"，把第一次开源贡献的门槛压到了最低：克隆、npm run dev、挑一个 good first issue、npm test && npm run check，你的第一个 PR 就可以提出来了。动手之后，也欢迎在社区的 Discord 里晒出你用 breakdown 导出的 MP4 🎬