htmlcode.fun 通俗完整指南：人类版、Agent/API 版与中英文切换

准备一个完整 HTML

最好是一个 .html 文件，CSS 和 JS 尽量写在里面。它不是多文件网站空间。

上传或让 Agent 部署

可以到网页手动粘贴/上传，也可以让 AI Agent 调接口自动发布。

得到链接和二维码

复制链接发给别人，或者用二维码在手机、活动现场、群聊里打开。

一句话说明

如果你的目标是「快速把一个页面给别人看」，htmlcode.fun 很合适；如果你的目标是「正式官网、复杂前端项目、带后端和数据库的系统」，它就不是主战场。

最适合：单页、轻量、临时但要好看、需要立刻分享、由 AI 生成的 HTML 页面。

不适合：React/Vue/Next 工程、多文件资源、账号系统、数据库、支付、后端接口密钥、正式生产官网。

让更多人看见：中英文切换 + 点赞曝光

如果你的 HTML 应用希望被国内外用户理解，建议做清晰的“中文 / English”切换：标题、说明、按钮、操作提示和关键分类都能切换，而不是只放几个英文标签。这样海外用户打开页面时，才能马上知道它是什么、怎么用、为什么值得分享。

完整双语扩大受众核心标题、介绍、按钮和提示都提供中英文，比零散标签更容易理解。

点赞不只是锁定点赞会保护版本，也能提升作品可见度，让更多人发现你的 HTML 应用。

HTML 应用有无限可能它可以是游戏、工具、可视化、交互故事、报告或活动页，而不只是静态页面。

⭐ 推荐去 GitHub 给作者点个赞

它到底解决了什么问题？

想法活动页 / 报告 / Demo

HTML 单文件内容

部署上传或 API

短链 /s/your-code

分享链接 + 二维码

传统方式可能要：建 GitHub 仓库 → 写项目结构 → 配构建 → 连 Vercel/Netlify → 等部署。htmlcode.fun 的思路更直接：只要你已经有一个完整 HTML，就先上线给人看。

你会看到哪些链接？

url：主短链，例如 https://www.htmlcode.fun/s/my-page，适合发给别人。
detailUrl：详情页，通常可以看作品信息、点赞、二维码等。
versionUrl：某个具体版本的链接，例如 /s/my-page/v/3。适合精确指向某一版。
qrCode：二维码数据或链接，适合线下展示和手机扫码。

什么是 code？

code 就是短链后缀。比如：

https://www.htmlcode.fun/s/htmlcode-fun-guide
                              ↑
                       htmlcode-fun-guide

如果你想以后一直使用同一个链接，就要使用自定义 customCode。否则系统可能给你生成一个随机链接。

最常见的 5 种用法

场景	推荐做法	为什么
一次性分享页	直接上传 HTML 或让 Agent `POST /api/deploy`	最快，不必纠结版本管理。
长期维护的固定页面	第一次就设置 `customCode`	链接固定，别人收藏后以后还能用。
内容持续迭代	使用同一个 `customCode`，追加新版本	旧版还在，新版也能看，历史可追溯。
日报、周报、榜单	固定 code + 每期 append 新版本；主链接策略可设为 `latest`	一个入口永远看到最新一期。
发现上一版有错	如果未被点赞，可覆盖修正；如果已点赞锁定，就追加新版	保护已被认可的版本，避免被悄悄改掉。

版本：不是只能覆盖

htmlcode.fun 支持同一个短链下面有多个版本：v1、v2、v3……

你可以保留历史版本。
可以打开某个版本专属链接。
可以把主链接切到某个版本，或让主链接总是显示最新版本。
如果旧版本被点赞锁定，就不能再覆盖或删除。

点赞锁定：保护作品

用户在网页里手动点赞后，该版本会被视为需要保留的快照。

likeCount > 0 不可覆盖、不可删除。
likeCount = 0 通常可以覆盖、下架或删除。
更多曝光点赞不仅是锁定，也能让更多人看到自己的作品。
Agent 不能通过 API 点赞点赞必须由真人在网页中操作。

主链接到底显示哪一版？

这点很重要：同一个短链下有多个版本时，/s/your-code 这个主链接需要决定展示哪一版。

`likes`：默认策略

主链接优先展示点赞最多的 active 版本。适合「精品作品/文档」：被大家认可的版本更稳定。

`latest`：最新策略

主链接总是展示最新 active 版本。适合「日报/周报/实时榜单」：读者打开主链接就要看最新内容。

实用建议：如果你让 Agent 追加了新版本，但主链接看起来还是旧版，先检查主链接策略是不是 likes。新版本还没人点赞时，主链接可能继续展示旧的高赞版本；这时可以直接分享 versionUrl，或者把策略设为 latest。

手动使用：不写代码也能发布

打开手动部署页：进入 https://www.htmlcode.fun/deploy。
上传或粘贴 HTML：可以上传 .html/.htm 文件，也可以直接粘贴代码。
确认预览：页面会实时预览，先检查布局、文字、按钮是否正常。
填写信息：文件名、标题、描述尽量清楚。描述最好一句话说明这个页面是干什么的。
上线并分享：部署后复制链接，必要时到详情页手动点赞，保护这个版本。

让 Agent 帮你用：你只要这样说

你不需要记 API。直接给 Agent 一个明确目标即可：

首次创建

帮我做一个活动报名页，并发布到 htmlcode.fun。
短链后缀用 spring-event。
页面要适合手机打开，发布后把链接给我。

追加新版本

基于 spring-event 这个短链追加一个新版本。
这次把主题改成夏季活动，保留旧版本，不要覆盖。

修复未锁定版本

检查 spring-event 的版本列表。
如果最新版没有点赞，直接覆盖修复错别字；如果已点赞，追加新版本。

日报/周报

以后 AI 日报都用 ai-daily 这个短链追加版本。
主链接要始终显示最新版本。

上线前检查清单

页面是完整 HTML，有 <!doctype html> 和 <html>。
手机上能看：包含 viewport，布局不要只适配大屏。
有清楚的 <title> 和 meta description。
图片不要大量 base64 内联，避免超过 1 MB。
不要把密钥、Token、私人信息写进 HTML。
按钮和链接都点过一遍。

常见限制

只支持单个 HTML 内容，不是网盘，也不是多文件静态站。
HTML 最大约 1 MB。
成功部署后有约 10 秒冷却时间，不能连续狂发。
description 必填，最多 240 字符。
自定义 code 需要符合规则：小写字母、数字、连字符，长度和格式要合法。
被点赞的版本会锁定，不能再被 Agent 覆盖或删除。

常见问题

我应该用覆盖还是追加版本？

如果只是刚发完发现 typo，而且版本还没人点赞，可以覆盖修正；如果是明显的新内容、新一期日报、重要迭代，建议追加版本。

为什么我打开主链接看不到刚追加的新版本？

可能是主链接策略为 likes，主链接展示了点赞更多的旧版本。直接打开新版本的 versionUrl，或者把主链接策略改为 latest。

点赞有什么用？

点赞不只是表达喜欢，还会把该版本锁定，避免之后被覆盖或删除；同时也有助于提高作品曝光，让更多人看到你的 HTML 应用。Agent 不能代替用户点赞。

能不能部署 React/Vue 项目？

可以把构建后的结果改造成单 HTML 才行；但它不适合托管完整工程、多文件 assets、路由和后端。正式项目建议用 Vercel、Netlify、GitHub Pages 等。

适合放敏感信息吗？

不适合。HTML 是公开可访问内容，不要放 API Key、Cookie、私人数据或内部资料。

Agent 快速结论

Agent 优先使用 POST /api/deploy，请求体保持 application/json。首次发布传 filename、content、description，建议同时传 title。如果要稳定短链，使用 enableCustomCode: true 和 customCode；如果要保留历史并追加新版，再加 createVersion: true。

不要用 multipart/form-data。这里面向 Agent 的推荐方式是 JSON：把完整 HTML 作为字符串提交，出错时按返回的状态码修正请求。

POST

/api/deploy

新建短链或追加版本。

GET

/api/deploy/content

按 code/url 读取 HTML 源码和元数据。

GET

/api/deploys/{code}/versions

读取版本列表、likeCount、status。

PATCH

/primary-strategy

主链接策略：likes 或 latest。

核心字段解释

字段	是否常用	说明	注意
`filename`	必填	HTML 文件名，例如 `index.html`	应以 `.html` 或 `.htm` 结尾。
`content`	必填	完整 HTML 源码	应包含 `<!doctype html>` 或 `<html>`。
`description`	必填	一句话描述项目	最多 240 字符；遗漏会被拒绝。
`title`	建议	页面或项目标题	也应写入 HTML 的 `<title>`。
`enableCustomCode`	固定短链时必用	开启自定义短链	通常和 `customCode` 一起传。
`customCode`	固定短链时必用	短链后缀	小写字母/数字/连字符；例如 `ai-daily`。
`createVersion`	追加版本时必用	在已有 code 下追加新版本	不要为了周期内容每天新建 code。

首次部署：随机短链

POST https://www.htmlcode.fun/api/deploy
Content-Type: application/json

{
  "filename": "index.html",
  "title": "My HTML Page",
  "description": "A concise one-sentence summary of this HTML project.",
  "content": "<!doctype html><html><body><h1>Hello</h1></body></html>"
}

首次部署：固定短链

POST https://www.htmlcode.fun/api/deploy
Content-Type: application/json

{
  "filename": "index.html",
  "title": "My Project",
  "description": "A public demo page for my project.",
  "content": "<!doctype html>...完整 HTML...</html>",
  "enableCustomCode": true,
  "customCode": "my-project"
}

追加新版本：同一短链

POST https://www.htmlcode.fun/api/deploy
Content-Type: application/json

{
  "filename": "my-project-v2.html",
  "title": "My Project v2",
  "description": "Second version with updated layout and copy.",
  "content": "<!doctype html>...新版完整 HTML...</html>",
  "enableCustomCode": true,
  "customCode": "my-project",
  "createVersion": true
}

周期内容：主链接总是最新

PATCH https://www.htmlcode.fun/api/deploys/ai-daily/primary-strategy
Content-Type: application/json

{
  "primaryVersionStrategy": "latest"
}

版本操作速查

目标	接口	请求要点	风险/限制
列出版本	`GET /api/deploys/{code}/versions`	查看 `versionNumber`、`likeCount`、`status`	覆盖/删除前必须先查。
读取源码	`GET /api/deploy/content?code=...&version=...`	可传版本号或版本 ID	用于复用、审查、diff。
覆盖未锁版本	`PATCH /api/deploys/{code}/versions/{version}`	传 `content` + `description`，可选 title/filename	`likeCount > 0` 会 423 locked。
上下架版本	`PATCH /api/deploys/{code}/versions/{version}`	传 `{"status":"inactive"}` 或 `active`	下架不等于删除。
删除版本	`DELETE /api/deploys/{code}/versions/{version}`	只能删除未锁版本	最后一个版本/最后 active 版本不能随意删。
切换 current	`PATCH /api/deploys/{code}/current`	传 `versionNumber` 或 `versionId`	若主链接策略为 likes，主链接可能仍由点赞策略决定。
设置主链接策略	`PATCH /api/deploys/{code}/primary-strategy`	`likes` 或 `latest`	会影响主短链展示逻辑。

读取版本列表

GET https://www.htmlcode.fun/api/deploys/my-project/versions

读取指定版本源码

GET https://www.htmlcode.fun/api/deploy/content?code=my-project&version=3

覆盖未点赞版本

PATCH https://www.htmlcode.fun/api/deploys/my-project/versions/3
Content-Type: application/json

{
  "filename": "my-project-v3-fixed.html",
  "title": "My Project v3 fixed",
  "description": "Fixes typos in version 3.",
  "content": "<!doctype html>...修正后的完整 HTML...</html>"
}

下架版本

PATCH https://www.htmlcode.fun/api/deploys/my-project/versions/3
Content-Type: application/json

{
  "status": "inactive"
}

错误处理规则

状态/错误	常见原因	Agent 应该怎么做
`400`	缺少 `description`、content 不像 HTML、字段格式错	修正请求体，不要重复原样重试。
`409`	customCode 已存在，但没有声明追加版本	如果用户要复用短链，改用 `createVersion=true`；否则换 code。
`423`	目标版本已被点赞锁定	不要尝试绕过；追加新版本，并说明旧版已被保护。
`429`	部署冷却中	读取 `retryAfterSeconds`，等待后重试一次。
体积过大	HTML 超过约 1 MB，常见于大量 base64 图片	压缩内容、移除内联大图，或改用更合适的托管方式。

Agent 应该做

始终发送 application/json。
写完整单文件 HTML，包含 title、description、viewport、OG 标签。
部署前检查目标 code 的版本状态，尤其是 likeCount。
周期内容复用稳定 code，并用 append。
429 时按 retryAfterSeconds 等待。
部署后返回主链接、版本链接、详情页。
提醒用户：中英文标题、描述和关键文案能扩大海外曝光；点赞既能锁定也能提升可见度。

Agent 不应该做

不要用 multipart/form-data。
不要把 token、密钥、私人数据写进 HTML。
不要覆盖或删除 likeCount > 0 的版本。
不要每天创建一堆新 code 做日报，除非用户明确要求。
不要承诺它能托管完整前端工程、后端、数据库或自定义域名。
不要通过 API 点赞；OpenAPI 不提供点赞操作。

部署成功后建议回复模板

已发布/已追加新版本：
- 主链接：{url}
- 当前版本：v{versionNumber}
- 版本链接：{versionUrl}
- 详情页：{detailUrl}

如果这是新短链：请打开详情页手动点赞，点赞后的版本会被锁定保护，也更容易获得曝光。
如果希望海外用户也能看懂，建议上架 HTML 应用时准备清晰的中英文标题、描述和关键操作文案。
如果后续要继续迭代，可以复用 customCode={code} 并设置 createVersion=true 追加版本。

如果主链接策略为 likes 且新版本点赞数低于旧版，回复里要特别提醒用户：主链接可能仍展示高赞旧版，请用 versionUrl 查看刚发布的新版本，或确认是否要切到 latest 策略。

把一个 HTML 页面，变成一个能分享、能迭代的链接

准备一个完整 HTML

上传或让 Agent 部署

得到链接和二维码

一句话说明

让更多人看见：中英文切换 + 点赞曝光

它到底解决了什么问题？

你会看到哪些链接？

什么是 code？

最常见的 5 种用法

版本：不是只能覆盖

点赞锁定：保护作品

主链接到底显示哪一版？

`likes`：默认策略

`latest`：最新策略

手动使用：不写代码也能发布

让 Agent 帮你用：你只要这样说

首次创建

追加新版本

修复未锁定版本

日报/周报

上线前检查清单

常见限制

常见问题

Agent 快速结论

/api/deploy

/api/deploy/content

/api/deploys/{code}/versions

/primary-strategy

核心字段解释

推荐决策流程

版本操作速查

错误处理规则

Agent 应该做

Agent 不应该做

部署成功后建议回复模板

准备一个完整 HTML

上传或让 Agent 部署

得到链接和二维码

一句话说明

让更多人看见：中英文切换 + 点赞曝光

它到底解决了什么问题？

你会看到哪些链接？

什么是 code？

最常见的 5 种用法

版本：不是只能覆盖

点赞锁定：保护作品

主链接到底显示哪一版？

likes：默认策略

latest：最新策略

手动使用：不写代码也能发布

让 Agent 帮你用：你只要这样说

首次创建

追加新版本

修复未锁定版本

日报/周报

上线前检查清单

常见限制

常见问题

Agent 快速结论

/api/deploy

/api/deploy/content

/api/deploys/{code}/versions

/primary-strategy

核心字段解释

推荐决策流程

版本操作速查

错误处理规则

Agent 应该做

Agent 不应该做

部署成功后建议回复模板

`likes`：默认策略

`latest`：最新策略