先选一条路
照着这张表挑，不用全看：
| 你想做的事 | 走哪条 | 要 GitHub 账号吗 |
|---|---|---|
| 给某张图补 / 改资料（难度、标签、作者、视频、来源…） | ① 网页表单 | 不用 |
| 有一大段背景故事想交 | ① 网页表单（选「背景故事」） | 不用 |
| 一次说好几件事，或者一整段攻略 | ② 提 issue | 要（注册免费） |
| 想直接改文件，或者一次改很多张图 | ③ 提 PR | 要 |
| 想给某张图换封面（要传图片） | ④ 传封面，或把图发给站长代传 | 要（注册免费，且必须先 Fork） |
| 什么都不想学，把东西发过来就行 | ⑤ 找站长 | 不用 |
动手之前，先认清两件事
1. 「地图英文名」是什么
就是地图详情页标题下面那行小字，也是网址里 /maps/ 后面那一段， 例如 ze_obj_abyss_v2、ze_ffvii_mako_reactor。 下面所有操作都要用到它，不是 Steam 的分片名（2001-ze_xxx-123456 那种）。
2. 「原稿」和「打印稿」，只能改原稿
| 文件 | 能不能改 | |
|---|---|---|
| ✅ 原稿 | data/research/<地图英文名>.json | 改这里，网站从它生成条目内容 |
| ❌ 打印稿 | src/content/maps/<地图英文名>.mdx | 脚本自动生成的，手改会被整段覆盖（真发生过好几次） |
怎么分辨：打开那个 .mdx，里面搜 generated by。搜得到就是自动生成的（别改，去改 JSON）；搜不到就是手写条目（直接改它才对）。 站上目前只有 3 张是手写的：ze_ffvii_mako_reactor、ze_lotr_minas_tirith、ze_pirates_port_royal。
① 网页表单（最省事，不用账号）
- 打开地图库找到那张图 → 进详情页 → 看右侧栏的「补充 / 纠错」， 点 ✏️ 补充这张图的资料。
或者直接打开 投稿表单，在里面输地图名（中文名也行）也能进。 - 在「要提交哪一项」里选这次要补什么 —— 一次只能提交一项， 要补好几项就提交几次。
- 填内容。表单会显示条目现在的值，照着改不容易出错； 下面的「理由 / 来源」和「你的昵称」都是选填，但来源很重要（见下）。
- 点提交。会给你一个投稿编号，凭它可以在表单页下面查审核状态。
表单里能填什么
下面这张表由站点的字段定义直接生成，和表单、服务器校验是同一份，所以不会对不上：
| 字段 | 能填什么 | 说明 |
|---|---|---|
| 难度 | 入门 / 简单 / 普通 / 困难 / 火星 / 入土 / 未知 | 必须从这几个里选 |
| 标签 | 每行一个，最多 12 个，每个最多 24 字 | 整组替换，不是追加 整组替换 |
| 作者 | 最多 120 字 | 尽量与工坊署名一致 |
| 署名详情 | 最多 300 字 | 多作者 / 原作与移植的区分 |
| 版本 | 最多 40 字 | |
| 人数 | 最多 40 字 | 如「最多 64 人」 |
| 时长 | 最多 40 字 | 如「约 40 分钟」 |
| 关卡数 | 1 ~ 30 的整数 | |
| 攻略视频 | 每行一个 https 链接，最多 12 条 | 每行一个，https 开头。B 站和 YouTube 会直接嵌播放器，其它站会显示成链接 追加合并，不会顶掉已有的 |
| 资料来源 | 每行一个 https 链接，最多 12 条 | 每行一个，https 开头 追加合并，不会顶掉已有的 |
| 地图封面 | 一张图：浏览器里自动裁成 16:9、压成 webp（上限 700 KB）再上传，不用自己处理 | 选一张横向图（16:9 最好）。会在你的浏览器里自动裁成 16:9、压成 webp 再上传，不用自己处理 替换当前人工封面（渲染图仍在，删掉人工封面即回退） |
| 背景故事 | 最多 4000 字 | 地图的剧情、设定与来历，可以分多段写。支持简单 Markdown，不支持 HTML 与 MDX |
| 补充说明 / 纠错 | 最多 4000 字 | 纯文本，支持简单 Markdown，不支持 HTML 与 MDX |
② 提 issue（会填表就行）
适合「一次说好几件事」或者「有一整段攻略想交」：不用改任何文件，填空就行。
- 注册并登录 GitHub（免费），打开仓库hhjjdsj/ze-map-site
- 点上方 Issues → 右侧绿色按钮New issue
- 选模板 补充地图资料，按格子填：地图名（中文名也行）、想补充哪方面（可多选）、具体内容、来源链接、署名
- 点 Create 提交，等站长处理
其它模板：报告网站问题（页面报错、链接失效、显示错乱）、其它建议。
③ 提 PR（直接改文件，全程网页操作）
适合熟悉 GitHub 的人，或者想一次改很多张图。
- 在仓库里找到
data/research/<地图英文名>.json，点开它 - 点右上角的铅笔图标（Edit this file）
- 改字段（能填什么见上面那张表；难度只有 入门/简单/普通/困难/火星/入土/未知 七种）
- 滚到页面底部，写一句「改了什么」，点 Propose changes
- 下一页点 Create pull request，再点一次确认
GitHub 会自动帮你复制一份仓库、开好分支，fork / branch 这些概念你都不用管。 提交后仓库会自动跑一遍检查，结果直接显示在 PR 页面上，有问题会告诉你哪里不对。 JSON 每个字段的详细写法（含填空模板的样子）见data/research/README.md。
JSON 的标点很严格，这是新手最容易翻车的地方：
- 每个字段末尾要有英文逗号
,（最后一行不要） - 引号要成对，用英文双引号
"，不能用中文引号“ - 字段名后面是冒号，写成
"sources"[就错了 - 字段名拼错（比如把
author写成awthor）语法上没问题， 但那条内容会静默消失 —— 现在检查会把它抓出来并提示正确写法
不确定就少改一点，或者改用 ① 的表单。
④ 换地图封面（要传图片）
推荐：直接在投稿页传，不用 GitHub 账号。在地图详情页右侧栏点「✏️ 补充这张图的资料」→ 在「要提交哪一项」里选地图封面 → 选一张图。图片会在你的浏览器里自动裁成 16:9、压成 webp（通常几十 KB）再上传， 站长审核通过后就换上了，和本站其它社区内容一样。
地图封面默认是脚本从地图数据渲染的（俯视密度图 + 实体点）。觉得某张图有更好看的封面，可以换成自己的图。 这张图会同时用在两处：地图库卡片（16:9 画幅）和详情页顶部（满宽背景大图，上面压了一层暗色遮罩）， 所以挑横向的图。想直接改成文件（提 PR）也行，下面是那条路 —— 但它必须先 Fork：
⚠️ 这一步必须先 Fork，不能直接往本站仓库传。你在这个仓库没有写权限，直接在目录里点「Add file → Upload files」会被 GitHub 拒绝 （提示 You need write access to this repository）。 正确做法是先把仓库复制一份到你自己的账号下，在你自己的副本里上传，最后发一个 PR 回来：
- 打开仓库hhjjdsj/ze-map-site，右上角点 Fork → Create fork（得到
你的用户名/ze-map-site） - 在你自己那份副本里打开public/images/covers/custom/ 目录
- Add file → Upload files，把图片拖进去
- 文件名必须正好是「地图英文名」，例如
ze_obj_abyss_v2.jpg。 格式.jpg/.png/.webp都收 - 拉到底 Commit changes（提交进你自己的副本，不会影响本站）
- 回到原仓库 hhjjdsj/ze-map-site —— 顶部会出现 Compare & pull request； 没看到就点 Contribute → Open pull request，写一句「换了 xx 的封面」再 Create pull request
嫌折腾？直接把图发给站长（⑤ 里那个 QQ）就行，站长在本地跑npm run cover:set 代传：会自动裁成 16:9、压成 webp，文件名也帮你对上。 投稿表单目前只收文字字段，还传不了图片—— 想自助传图的话跟站长说一声，可以加。
| 要求 | 建议 |
|---|---|
| 比例 | 横向 16:9。竖图会被裁成中间一条 |
| 宽度 | 1280px 左右最合适，至少 640px（详情页顶部会放大当背景） |
| 体积 | 尽量 300 KB 以内，硬上限 800 KB（超了检查会红）。截图直接存 PNG 往往有 1~2 MB，存成 JPG（画质 80 左右）就行 |
⚠️ 文件名写成 Steam 分片名（2001-ze_xxx-123456）或者拼错一个字符，这张图永远不会显示—— 而页面和构建全都正常，你不会收到任何报错。 所以上传后请确认 PR 页面上的检查是绿的。
为什么换封面必须用「上传」，不能用铅笔？GitHub 的铅笔编辑只能改文字文件 —— 图片这类二进制文件它不给编辑器。 不过新增、替换、删除图片都能在网页上完成，不用装任何东西（都要在你自己 fork 的副本里做）：
- 换成另一张：在你 fork 的
custom/里还是 Add file → Upload files，文件名和路径保持一模一样，就是覆盖（PR 里会显示成修改） - 换回脚本渲染的封面：在
custom/里点开那张图 → 右上角⋯ → Delete file → 同样提一个小 PR。不用改任何配置
⑤ 什么都不想学：直接联系站长
QQ 3157410575（宇宙机器人）。把资料发过来就行 —— 文字、截图、视频链接、攻略原文都可以， 整理的事交给站长。
提交之后会发生什么
| 你走了哪条 | 接下来 |
|---|---|
| ① 表单 | 进人工审核队列（凭编号可查）→ 站长审核 → 通过后写进站点的社区补充， 自动重新构建，通常几分钟内就能在页面上看到，并署上你留的昵称 |
| ② issue | 站长看到后整理进站点，可能用你留的方式追问细节 |
| ③④ PR | 自动检查跑一遍 → 站长合并 → 自动构建部署上线 |
审核不通过或被搁置，通常是这几种原因：
- 没有来源 —— 查不到的宁缺勿假，写「网上说」没法核对
- 说法有争议（比如难度），会先挂起来等更多依据
- 整段搬运他人文章 —— 引用请注明出处，别原样复制
- 格式没法用（JSON 坏了、文件名不对），会退回让你改
站里还没有的新地图
地图条目来自服务端实体数据与工坊数据的定期同步，新图通常会自己进来，不需要谁手动添加。三种情况例外：
- 刚发布、还没进同步：等下一轮同步，或者提个 issue 说一声
- 想给站上还没收录的图写资料：直接提 issue，站长会先把条目建起来
- 需要路线图、视频嵌入这类富内容：这类是手写条目维护的，交给站长
给开发者的命令
在本机跑开发时用得上，普通投稿完全不需要：
| 命令 | 作用 |
|---|---|
npm run build | 完整构建（含日期清单、生成条目、搜索索引） |
npm run maps:generate | 只从 data/research/ 重新生成条目 |
npm run content:verify | 校验资料 JSON（来源、难度、字段名、可疑措辞） |
npm run cover:set -- <地图名> <图片> | 本机裁图并换成人工封面（自动转 16:9 webp） |
npm run cover:verify | 校验人工封面（文件名、格式、体积、比例） |
npm run content:links | 扫全站站内链接与静态资源，查死链 |
注意事项
- 请尽量附上可核对的来源链接，避免无法验证的说法
- 不要直接整段搬运他人文章；引用请注明出处
- 地图版权归原作者，本站只做整理