POLARIS · 作品外链

让自己的作品
在卡片上点得开

作品卡底部默认只有一个「查看独立页」，那只是站内的一张说明页。想让人真的看到你做的东西，需要给它挂一个外链。这里有两种挂法：本机预览（今天就能用）和 GitHub 仓库（永久、能给别人看）。两条都做完只要半小时。

方案 A 本机预览 方案 B GitHub 仓库

	生效范围	耗时	适合
方案 A	只有你这台电脑（或同一 WiFi、同一 Tailscale 网络）	5 分钟	自己演示、答辩现场、给老师当面看
方案 B	任何人，任何设备，永久	30 分钟	投递、写进简历、发给校外的人

两个可以同时挂：先把 A 做出来验证流程，再补 B。链接互相不冲突，改一次只影响一件作品。

00动手之前：作品得先能「被浏览器打开」

不管走哪条路，作品本身要满足四条，否则链接点开是白屏。

检查项	要求	不对会怎样
入口文件	作品文件夹最外层有 `index.html`	点开看到一串文件名目录
资源路径	全部用相对路径 `./img/a.png`、`assets/x.js`	本机能看，传上去图全裂
大小写	文件名大小写与代码里写的一致（`Cover.png` ≠ `cover.png`）	Windows 本机正常，GitHub 上 404
体积	单个文件不超过 100MB（GitHub 硬上限）	push 直接被拒

01方案 A · 本机预览

原理很简单：在你电脑上开一个小服务，把作品文件夹变成一个网址（http://127.0.0.1:8080/），再把网址填进作品卡。

要用的东西都在哪

C:\Users\29427\Desktop\网页\_tools\creator-kit\
  start-local.bat     双击它 = 起本机预览
  serve-local.py      背后的服务（会打印三个地址）
  git-publish.bat     方案 B 用（下一节）
  git-publish.ps1     方案 B 用

五步走完

把作品文件夹准备好随便放哪，比如 D:\works\hotkey-overlay，里面最外层要有 index.html。

把作品文件夹拖到 start-local.bat 上松手 会弹一个黑窗口，打印三行地址：

本机访问 : http://127.0.0.1:8080/     <- 只在这台电脑有效
局域网   : http://192.168.x.x:8080/   <- 同一 WiFi 的手机可打开
Tailscale: http://100.x.x.x:8080/     <- 装了 Tailscale 的设备可打开

窗口别关，关了服务就停。

复制「本机访问」那一行粘到浏览器地址栏回车，先自己确认页面是好的。看到白屏或目录列表，回看 00 节。
把地址填进站点在 C:\Users\29427\Desktop\网页 目录下打开终端，执行：
```
python tools/set-work-link.py --slug hotkey-overlay --url "http://127.0.0.1:8080/" --label "本机预览"
```
--slug 换成你的作品代号（清单见 03 节），--label 就是按钮上的字。
刷新站点看效果作品卡底部会多出一个高亮的「本机预览 ↗」，点开直达你的作品；原来的「查看独立页」会自动改名成「站内档案」，两个按钮并存。

三条必须知道的限制
① 黑窗口一关，链接立刻失效（浏览器显示「无法访问此网站」）；答辩前记得先启动。
② 端口被占用时脚本会自动顺延到 8081、8082…… 窗口里显示哪个就用哪个，并且要重新执行一次第 4 步把新端口写进去。
③ 127.0.0.1 只对这台电脑有意义。别人在手机或别的电脑上点，是打不开的——那种情况用「局域网」那行（同一 WiFi），或者直接走方案 B。

想给同一 WiFi 的人看：把第 4 步的地址换成窗口里「局域网」那行，例如 --url "http://192.168.1.7:8080/"，标签写「现场预览」。第一次启动时 Windows 可能弹防火墙提示，点允许访问（专用网络），否则手机连不上。

02方案 B · GitHub 仓库

做两件事：把作品推到 GitHub，再决定要不要开网页预览。仓库链接一定有效；网页预览要额外开一个开关。

B-1 建仓库（网页上，1 分钟）

打开 github.com/new
填名字只能英文、数字、连字符，例如 hotkey-overlay。名字里不要有中文和空格。
选 Public私有仓库别人打不开，链接等于没用。
不要勾 Add a README / .gitignore / license（勾了会和本地首推打架，得多一步 pull）。
点 Create repository，复制页面上那个 https://github.com/你的用户名/仓库名.git。

B-2 一键上传（双击，30 秒）

双击 git-publish.bat
第一问：把作品文件夹拖进黑窗口再回车（直接回车 = 用 bat 所在文件夹）。
第二问：粘刚才复制的仓库地址，回车。
等它跑完。首次推送会弹一个 GitHub 登录窗口，浏览器里点授权即可（只需一次，之后记住）。
看结果：窗口最后出现 [ok] pushed 就是成功，并会打印仓库地址、Pages 开启地址、以及填链接的命令。

推送失败先看这三条：仓库地址粘错（要 .git 结尾那串）／登录没走完／仓库不属于你。改完再双击一次，脚本是幂等的，重复跑不会把事情搞坏。

B-3 想要网页预览就开 Pages（可选，2 分钟 + 等 1~3 分钟）

进仓库 Settings → Pages
Source 选 Deploy from a branch
Branch 选 main，目录选 / (root)，点 Save
等构建首次 1~3 分钟，刷新页面看到绿色提示后，地址是
```
https://你的用户名.github.io/仓库名/
```

纯前端（HTML/CSS/JS）作品能直接跑；需要后端接口、数据库的作品，Pages 只能显示前端壳子，这种情况链接填仓库地址更诚实。

B-4 填进站点（二选一）

# 填仓库地址（别人能看代码）
python tools/set-work-link.py --slug hotkey-overlay --url "https://github.com/你的用户名/hotkey-overlay" --label "GitHub 仓库"

# 填网页预览地址（别人直接看作品）
python tools/set-work-link.py --slug hotkey-overlay --url "https://你的用户名.github.io/hotkey-overlay/" --label "在线预览"

以后更新作品：改完文件，再双击一次 git-publish.bat（仓库地址会被记住，只问文件夹），Pages 会在 1 分钟内自动重建。

03链接填在哪：slug 清单与命令

所有外链存在一处：sites/polaris-hub/js/main.js 里的 WORK_LINKS 表。手改也行，但用脚本更安全——它会先备份（main.js.bak-时间戳），改完自动做语法检查，不过就回滚。

python tools/set-work-link.py --list                     # 看现在填了什么
python tools/set-work-link.py --slug SLUG --url URL --label 按钮文字
python tools/set-work-link.py --slug SLUG --clear        # 撤掉这条

九个自有项目的 slug（--slug 就用这个）：

photo-to-3d　照片重建　PL-GX004
macosify　桌面改造　PL-GX005
maker3d-print　造物车间　PL-GX006
dsh-orb　桌面悬浮球　PL-GX007
momo-station　工作站中枢　PL-GX008
prompt-forge　出图工坊　PL-GX009
hotkey-overlay　按键浮层　PL-GX001
fundamental-physics　基础物理　PL-GX002
dsh-plugin-community　插件社区　PL-GX003

现在表里留了一条示例：photo-to-3d 指向 http://127.0.0.1:8080/，用来让你先在卡片上看到按钮长什么样。 正式上线前要么换成真实地址，要么撤掉：python tools/set-work-link.py --slug photo-to-3d --clear。

04出问题照这张表查

现象	原因	怎么修
点开「无法访问此网站」	服务没起，或端口变了	重新双击 start-local.bat，按窗口里的地址更新链接
点开是一串文件名	文件夹里没有 index.html	把入口文件改名成 index.html 放最外层
本机正常，GitHub Pages 白屏	绝对路径 / 大小写 / 缺文件	全局搜 `C:\` 与 `file://`，全改成相对路径；核对大小写
Pages 打开是 404	分支选错、还在构建、仓库私有	Settings → Pages 确认 main + root；等 3 分钟；仓库改 Public
push 被拒：file exceeds 100MB	作品里有视频/模型大文件	大文件移到别处，或改用 Git LFS
push 报 Authentication failed	没登录 / 密码被弃用	用弹出的浏览器授权，或用 Personal Access Token 当密码
手机打不开局域网地址	不在同一 WiFi / 防火墙拦了	连同一 WiFi；控制面板允许 Python 走专用网络
改了链接站点没变化	浏览器缓存	Ctrl + F5 强刷
卡片上没出现新按钮	slug 写错，或没重新加载	`--list` 核一遍；确认没手改坏 WORK_LINKS 的结束标记

POLARIS 星辰创汇 · 作品外链教学 · 工具目录 网页\_tools\creator-kit\ · 命令目录 网页\tools\set-work-link.py

让自己的作品在卡片上点得开