使用说明 —— 网站维护手册

线上地址：https://uppjs.com 这份说明写给"完全不想碰命令行"的你，全部操作都是双击。

一、这个网站由什么组成

这几个文件各司其职，日常你只会碰第一个：

唯一要记住的规则：只改 README.md。
index.html、hub.html、说明书、robots.txt、sitemap.xml、manifest.webmanifest 都是每次自动生成的，手动改了下次会被覆盖。

关于说明书有两个版本

两者内容完全一致，都从 使用说明.md 自动生成。 你只需要维护 md 这一份，双击 2-更新网站.command 时 html 版会跟着一起更新——永远不会不同步。

📱 手机上想看？ 直接访问 https://uppjs.com/help.html。
（使用说明.html 和 help.html 是同一份内容，后者只是为了让网址好输入。）

二、日常只有两个动作

动作 1️⃣ 改内容

双击 1-编辑内容.command → 自动用 VSCode 打开 README.md。

具体操作（VSCode，你电脑上已经装了）：

为什么是 VSCode：改 Markdown 最顺手——有语法高亮、有实时预览、找东西有 Cmd + F、 还能按 Cmd + Z 一路撤销。项目里已经配好了 .vscode/settings.json： 长行自动换行、中文标点（：「」）不再被误报成"可疑字符"，打开就能用。

其他软件也能改，但没必要：

说到底 README.md 就是个纯文本文件，用哪个编辑器都行。
只有一条禁忌：别用 Word / Pages 这类富文本编辑器打开，它们会往里塞格式代码，把文件搞坏。

动作 2️⃣ 更新上线

双击 2-更新网站.command

它自动完成四件事：

大约 1 分钟后，https://uppjs.com 就是新内容了。

⚠️ 改完内容一定要双击第 2 个，否则线上看到的还是旧内容。

三、README 怎么写（重要）

一句话记住

- [软件名](链接)：这是干什么用的 ｜ 我的实际感受

冒号只用中文 ：；句尾不加句号；一行一条。

写错也不要紧——build.py 会自动纠正下面这些：中英文冒号、逗号、句号当分隔符都能认；句尾的 。 会自动去掉；名称里的括号备注会自动变成标签。你只要记住上面这一行。

一条条目由三部分构成

③ 和 ④ 之间用全角竖线 ｜ 隔开。网页上 ③ 跟在名称后面，④ 会另起一行、带一条竖线，视觉上分开。

- [Snipaste](https://zh.snipaste.com/)：截图贴图工具，按 F1 就能截｜用了三年，重装系统必装

这就是"完美"的答案：把三件事分开写

现在很多条目把 是什么、好不好用、什么版本 三件事挤在一句里，所以看起来乱。分开就清爽了：

判断标准：读名称能知道"这是啥软件"，读简述能知道"它是干这个的"，读点评能知道"你用下来的真实评价"。

💡 点评是这个清单最值钱的部分。网上的软件介绍到处都是，但"文件一多就卡""盗版太多，还在找笔中"这种话只有你能写。这是你区别于软件测评号的地方，值得每条都补一句。

标签：让名称保持干净

不要把版本号、属性、评价写进名称里。用括号写在名称后面，网页会自动变成彩色小标签：

自动识别规则：名称里 10 个字以内的括号内容会被抽成标签；超过 10 字（比如 （Loop loop habit track））会原样留在名称里。

推荐标记两种写法都行：☆ 放名称最前面，或 （荐） 放名称最后面——效果一样。

能识别的属性词：开源、免费、付费、绿色版、便携版、单文件、汉化、官方、破解、无广告、网页版、客户端、跨平台 能识别的平台词：Win、Windows、Mac、macOS、iPhone、iOS、iPad、Android、安卓、手机、浏览器、Chrome、Edge、Firefox、PC

结构：分类 / 分组 / 条目

## PC 软件

- 截图工具：
  - [Snipaste](https://zh.snipaste.com/)：截图贴图工具｜重装必装
  - [ShareX](https://getsharex.com/)：功能最多，但设置项太多

⚠️ 缩进统一用 2 个空格。现在 README 里有 2 格、4 格混用的情况，虽然脚本能正确解析，但自己看着容易乱。

已经统一掉的写法（你以前写得不一致的地方）

几个容易踩的小坑

元数据：给重点软件多写几行（可选）

普通的子条目是「附注」。但如果你用下面这 8 个词开头，网页会把它认成结构化字段，单独显示成一行小字，还能参与筛选和搜索。

写法就是普通子条目，缩进比父条目多 2 格：

- 本地跑模型：
    - [Ollama](https://ollama.com/)：命令行一行就能拉起本地模型。
        - 免费：是
        - 开源：是
        - 平台：Win / macOS / Linux
        - 坑：模型文件很占硬盘，动手前先看剩余空间
        - 验证：2026-10

三条注意：

1. 不写完全没问题。 没写元数据的条目一切照旧，可以只给重点软件写。
2. 键名必须是上面 8 个之一，换成别的词就会被当成普通附注。
3. 键和值之间要用冒号（免费：是），全角半角都认。

四、首次使用：macOS 的安全提示

第一次双击 .command 文件，macOS 可能弹这个：

"无法打开，因为它来自身份不明的开发者"

解决（只需做一次）：

1. 在文件上右键（或按住 Control 点一下）
2. 选「打开」
3. 弹出的窗口里再点一次「打开」

之后就能正常双击了。

如果双击后终端窗口一闪就没了，说明执行出错。可以在终端里运行一次看详细信息：

cd ~/IdeaProjects/js-ping.github.io && ./2-更新网站.command

五、访客能用到的功能（外观 / 收藏 / 导出 / 工具台）

右上角的「外观」按钮，每个访客都能自己调。设置只存在他自己的浏览器里，不影响别人，也不上传任何东西。

明暗三档

背景色

面板下半部分是色块，点一下整站换色。目前 8 个预设：

点「自定义…」还能用系统取色器挑任意颜色；「恢复默认」一键回到跟随系统 + 默认色。

不用担心看不清。 选定底色后，面板色、边框色、正文色、次要文字色都是从这个底色按对比度算出来的：深色底自动配浅字，浅色底自动配深字。实测标题对比度 ≥12:1，正文 ≥4.9:1，辅助文字 ≥3.2:1，都在无障碍标准线以上。

想加颜色 / 改颜色

打开 build.py，搜索 presets，找到一个数组，一行一个颜色：

{name: '暖阳', bg: '#f7efd9'},

• name：鼠标悬停时显示的名字
• bg：底色，十六进制颜色码

加一行就多一个色块，删一行就少一个（面板一行排 4 个，建议保持 4 的倍数，排版最整齐）。

想改「浅色 / 深色」这两个默认基准色，改 build.py 里的 THEME_CSS（这个常量被清单页和工具台共用，改一次两边都变）。

收藏、已装与导出

访客把鼠标移到任意条目上，名称右边会冒出 ☆ 收藏 和 ☐ 标记为已装 两个小按钮（手机上直接显示）。点一下变实心，再点取消。

右上角 「我的」 按钮里能看到这两个列表：

记录只存在访客自己的浏览器里（localStorage），换设备或清缓存就没了。这是刻意设计：不需要账号、不上传任何数据、不用买服务器。

工具台（导航页）

顶栏右边的 「工具台」 打开 hub.html，是一张总入口页，把所有模块列在一起：

想加新模块？ 打开 build.py，搜索 HUB_MODULES，往数组里加一行就行：

dict(t="文章归档", ico="▦", href="posts.html", st="live",
     d="公众号写过的长文按主题归档。"),

• t 标题 / ico 图标字 / href 链接 / d 一句话说明
• st="live" 可点击；st="plan" 显示灰色「规划中」占位，不可点
• 加一行就多一张卡片，删一行就少一张

直接跳到某个筛选

收藏、已装这些入口支持用网址参数直达，方便做外链或加书签：

装到手机主屏

本站有 PWA 配置（manifest.webmanifest + 图标）。手机上打开 uppjs.com，Safari 里点「分享 → 添加到主屏幕」，就能像 App 一样全屏打开。

故意没做 Service Worker 离线缓存：那会让改完的内容迟迟不更新，对「改 README 就该立刻生效」的站来说得不偿失。

六、常见问题

Q：我改了 README，但网页没变？ A：九成是忘了双击 2-更新网站.command。另外 EdgeOne 部署有约 1 分钟延迟，稍等一下；浏览器缓存可以按 Cmd+Shift+R 强制刷新。

Q：双击后提示「推送失败」？ A：绝大多数是网络问题。你的改动已经安全保存在本地，网络恢复后重新双击一次即可，不会丢东西。

Q：能直接在手机上改吗？ A：可以。在 GitHub 网页上直接编辑 README.md 并提交，然后……需要在电脑上双击一次 2-更新网站.command，因为 index.html 得在本地生成。如果不方便用电脑，见下面「进阶」。

Q：想改网站标题、栏目结构？ A：那些不在 README 里，在 build.py 里。用编辑器打开，找到最上面一大段 HTML 模板改。改坏了不用怕，git 里都有历史，随时能退回去。

Q：想调背景色，或者加一个新的预设配色？ A：访客自己就能调——右上角「外观」按钮，明暗 + 8 个底色 + 自定义取色器。要增删预设色块，改 build.py 里的 presets 数组，见第五节。

Q：我在自己电脑上点了收藏，换台电脑怎么没了？ A：正常。收藏和已装只存在那台设备的浏览器里（localStorage），不联网、不上传。换设备请用「我的 → 导出 Markdown」，把清单带走。

Q：想给某个软件加「坑」和「替代」这类信息？ A：在它下面缩进 2 格写一行 - 坑：xxx 就行，8 个可用键见第三节的「元数据」。不写也完全没问题。

Q：工具台里那些灰色的「规划中」卡片，怎么变成能点的？ A：两种做法。已有页面的（比如文章归档做出来后）→ 改 build.py 里 HUB_MODULES 那一行，把 st="plan" 改成 st="live"、补上 href，它就变亮了。还没做的功能（拼音搜索、条目对比）代码里已经留了接口位置，做的时候再填。

Q：手机上怎么用最方便？ A：Safari 打开 uppjs.com → 分享 → 添加到主屏幕。之后点图标就能全屏打开，像个 App。清单页右上角「工具台」也能当入口。

七、进阶：换托管商 / 双托管

站点同时支持挂在 GitHub Pages 和 腾讯云 EdgeOne Pages 上，两套互不干扰：

关键文件：edgeone.json

仓库根目录的 edgeone.json 是给 EdgeOne 看的构建配置，它会覆盖控制台里填的构建命令和输出目录。

{
  "installCommand": "exit 0",
  "buildCommand": "mkdir -p public && cp *.html favicon.ico favicon.svg robots.txt sitemap.xml public/",
  "outputDirectory": "./public",
  "headers": [
    {
      "source": "/*",
      "headers": [
        { "key": "Strict-Transport-Security", "value": "max-age=604800" },
        { "key": "X-Content-Type-Options", "value": "nosniff" },
        { "key": "Referrer-Policy", "value": "strict-origin-when-cross-origin" },
        { "key": "X-Frame-Options", "value": "SAMEORIGIN" },
        { "key": "Permissions-Policy", "value": "geolocation=(), microphone=(), camera=()" }
      ]
    }
  ]
}

意思就是：不装依赖、把 html 和图标/SEO 文件复制进 public/、发布这个目录，并给所有响应加一组安全头。

✅ 好处：你在控制台那几个容易填错的框（构建命令 / 输出目录）填什么都不影响结果，平台以这个文件为准。
❌ 不要删这个文件，删了就得靠控制台手填，容易出错。

安全响应头都加了什么

关于 HSTS 的实话：它是单向门——开启后浏览器在有效期内会强制所有访客走 HTTPS，用户端清不掉。

• 这里只设了 7 天（max-age=604800），没加 includeSubDomains、没加 preload，就是为了万一出问题能自动过期退回来。
• 加它的前提是两个域名的证书都已正常签发（现在已满足）。
• 想改或去掉：编辑 edgeone.json 把这一行删掉，或把 604800 改成别的秒数（0 = 关闭），然后双击 2-更新网站.command 推送即可生效。
• ⚠️ 以后如果再新增子域名（比如 img.uppjs.com），要先把它的证书配好——不然 HSTS 期间浏览器会拒绝访问。

新建项目时怎么填（容易填错的几栏）

⚠️ 加速区域是关键。选「含中国大陆」的话，添加自定义域名时会要求 ICP 备案号，域名还没备案就会卡死。
等以后备案下来了，再到项目设置把区域改成「全球可用区（含中国大陆）」——国内响应能从几百毫秒降到 50–90ms。

一个反直觉的现象（提前知道，别慌）

选了「不含中国大陆」之后，EdgeOne 给的 xxx.edgeone.app 临时地址在国内打不开，返回 401。 这是平台行为，不是部署失败——那个地址只对海外网络开放。

所以部署完不要用临时地址验证，直接跳到绑域名，用 https://uppjs.com 验证。 判断部署成没成功，看控制台的部署记录和构建日志：状态显示成功、日志里能搜到 cp *.html public/ 就对了。

绑定域名

刚改完 DNS 就点验证失败是正常的，等几分钟再点。

CNAME 记录值从哪来（★ 这一栏只能从控制台拿）

记录值 是 EdgeOne 分配给你的专属地址，没有固定值，别人拿到的不一样，控制台外拿不到。长这样：

a4285573.uppjs.com.dns.edgeone.site

注意结尾是 dns.edgeone.site，不是 edgeone.app（那是临时预览域名，不能当 CNAME 用）。

去哪看：EdgeOne Pages 控制台 → 进入 uppjs 项目 → 域名管理 / 自定义域名 → 点「添加自定义域名」→ 输入 uppjs.com → 页面会直接显示「请到 DNS 服务商添加以下记录」，那行 CNAME 的值就是它。

根域名 uppjs.com 和 www.uppjs.com 要分别添加，平台可能给出两个不同的值。

阿里云 DNS 怎么改（别删记录）

⚠️ 点记录右侧的「修改」，不要「删除」再「添加」。
删掉会立刻让网站 404（现在 uppjs.com 全靠这条 CNAME 指向 GitHub Pages 活着）。

✅ 那条 edgeonereclaim 的 TXT 验证记录，留着别动，以后重新绑域名还能复用。

判断改成功了没

Mac 终端跑 dig uppjs.com，看 CNAME 是不是等于 EdgeOne 给的值。

实测：EdgeOne 给的 CNAME 目标是 uppjs.com.pages.dnsoe5.com 这种格式（结尾是平台分配的域名），根域名和 www 共用同一个目标值。

证书（HTTPS）怎么来

EdgeOne 免费证书不是瞬间生效的，申请期间该域名的 HTTPS 访问本来就是不可用的——这是官方明确说明的正常中间态，不是配置错误。

申请路径（手动触发时用）：

证书由 TrustAsia / Let's Encrypt 签发，90 天有效，到期前 15 天平台自动续期，不用管。

⚠️ 官方原话：「Makers 不会自动为您的域名分配 HTTPS 证书。」
也就是说，证书必须手动申请一次，干等是等不来的。
判断依据：域名管理页的 HTTPS 列。显示「未配置」= 从没申请过。

⚠️ 最容易走错的坑：两个「配置」页不是一回事

控制台里有两个长得很像的页面，点错就找不到证书在哪：

一句话判断：页面上能看到「边缘 HTTPS 证书」这张卡片，才是走对了。

只看到 HTTP/2 / IPv6 / 关联环境 → 走错了。退回域名管理列表页，点该域名那一行最右侧 HTTPS 列里的蓝色「配置」（不是点域名名字）。

故障速查表（按现象定位）

两个容易误判的点

• 中文文件名要 URL 编码：使用说明.html 在地址栏里会自动变成 %E4%BD%BF%E7%94%A8%E8%AF%B4%E6%98%8E.html，这是正常的。用工具直接测时如果不编码会误报 404。手机上想看说明书，直接用 uppjs.com/help.html 更省事。
• DNS 生效比想象中快：实测改完 10 分钟内，阿里云/腾讯/Google 三大公共 DNS 就都返回新值了。真正慢的是证书签发。

CNAME 文件是给 GitHub Pages 用的，EdgeOne 不读它，保留不管即可。

日常更新流程完全不变：双击 2-更新网站.command → 推送 → 两边都会自动重新部署。

当前状态（2026-10-01 实测）

EdgeOne 迁移已全部完成，不用再做任何控制台操作。

备案：想真正提速时再做

当前决定（2026-10-01）：暂不备案。 原因是要花钱——备案本身免费，但必须先在国内某家云厂商买一项云资源当"接入凭证"（最低约 ¥68–300/年的轻量服务器），而它除了让网站变快之外没有任何别的用处，还得记着到期续费，否则备案会失效。

>

触发条件：有人反馈打不开、或者有了明确要引流的场景，再动手。下面全部内容保留，到时候照着做即可。

先说结论：现在不做也完全能用。 不备案的天花板是 600~1400ms（走海外节点回来）；备案后大陆节点直连，能到 50–90ms。这是"更快"，不是"能用/不能用"。

备案是什么

向工信部登记你的网站信息，必须通过一家接入服务商（云厂商）提交。所以要备案，你需要在国内某家云厂商有一项云资源当"接入"——买一台最低配的轻量应用服务器就行，不用一直开着，费用以控制台为准。

你的域名 uppjs.com 注册在阿里云、实名已通过，所以走阿里云备案最顺（不用迁域名）。走腾讯云也可以（EdgeOne 是腾讯云的），但同样需要腾讯云那边的云资源。

材料清单

流程与耗时

⚠️ 一个真实的注意点：备案会核查网站性质，个人备案对内容有要求。你清单里有激活工具、绿色版之类的条目，备案时不要把这些作为网站定位去描述，按"个人软件使用记录"说明即可。各地管局口径略有差异，提交前可以先看云厂商备案页面的最新要求。

备案通过后要做什么

做完这些，国内访问就从几百毫秒降到几十毫秒。日常更新流程依旧不变。

📄 完整版见仓库 docs/备案操作手册.md，或在电脑上双击 备案操作手册.html。
那份手册写清了：怎么买最便宜的那台"备案用"服务器、控制台每一屏点什么、以及最容易被打回的五个坑。

八、数据安全与免责

• 所有内容只存在你自己的电脑和你自己的 GitHub 仓库里，本流程不上传任何数据到第三方。
• 页面是纯静态的，没有统计脚本、没有跟踪代码、不收集访客信息。
• README 里的第三方下载链接仅作记录，安全性与可用性请自行判断。