LittleLink v3.11.0 配置参数详解

LittleLink v3.11.0 配置参数详解:以 index.html 数据模型为主线,主题三态、SEO/OG 元数据、头像、按钮结构与品牌 CSS 变量、布局尺寸、Extended 扩展库与隐私页逐字段实测讲解;无 CLI、无环境变量、文件即配置、改完即生效。

LittleLinkLittleLink面板自托管2026/11/03

LittleLink v3.11.0 配置参数详解

目标:把 LittleLink v3.11.0 的全部「配置」讲透——它没有 CLI、没有环境变量、没有管理后台,index.html 文件本身就是配置。本文按页面数据模型逐字段拆解:主题三态、SEO/社交分享元数据、头像、按钮结构与品牌 CSS 变量、布局尺寸、Extended 扩展库与隐私页,每个参数给出默认值、修改方法与线上实测回显。已在 Ubuntu 24.04.5 LTS 服务器、Docker Compose 部署的 LittleLink v3.11.0(监听 8141 端口)上逐项实测通过;部署过程见 《LittleLink Docker Compose 部署指南》。

一、环境信息

项目值
操作系统Ubuntu 24.04.5 LTS(x86_64)
组件版本LittleLink v3.11.0(2026-07-28 发布,MIT)
部署形态Docker Compose(nginx:alpine 基础镜像,nginx/1.31.8),站点目录 bind mount
配置文件/opt/littlelink/site/index.html(默认 460 行、121 个示例按钮)
样式文件site/css/style.css(326 行)、css/brands.css(637 行、91 个 .button-* 品牌类)、css/reset.css(91 行)
图标库site/images/icons/(123 个 SVG)
验证入口http://localhost:8141/

⚠️ 注意:本文所有「源码回显」来自 v3.11.0 官方源码目录(/opt/littlelink/littlelink-3.11.0/),「线上回显」来自部署后的 http://localhost:8141/,两组互为镜像——挂载生效时二者内容一致(见 3.3 验证)。

二、前置条件

按 《LittleLink Docker Compose 部署指南》 完成部署后,确认服务在线且挂载生效:

curl -sI http://localhost:8141/ | head -5
HTTP/1.1 200 OK
Server: nginx/1.31.8
Date: Mon, 02 Nov 2026 17:52:09 GMT
Content-Type: text/html
Content-Length: 31818

Content-Length: 31818 即官方默认 index.html 的大小;后续任何配置修改都可用这个字段做「是否生效」的快速判据。

三、参数查看与修改方式

3.1 配置形态:文件即配置

LittleLink 的「配置参数」全部是 index.html 里的 HTML 元素与属性,修改流程 = 编辑文件 → 保存 → 刷新浏览器,无需重启、无需重建镜像(站点目录是 bind mount,nginx 按请求读盘)。

💡 技术拓展:自托管面板/导航类产品的配置形态不止一种,全量对比——

形态代表产品优点缺点
HTML 文件即配置(本文)LittleLink所见即所得、无格式学习成本、git 可管无校验,改错标签页面即坏
单一 YAMLHomer结构化、易读改错 YAML 整站不可用
多 YAML 分文件homepage分层清晰、模板变量文件间引用复杂
conf.yml + 构建Dashy功能参数丰富需了解构建缓存
GUI + 数据库Homarr、Heimdall在线编辑、有校验备份要导库、不可 diff

LittleLink 选「HTML 即配置」是设计取向:它本质是一个静态模板仓库,把自由度全部交给用户,代价是没有参数校验——本文第五章的逐字段讲解与「七、常见问题」的排障实录就是为了对冲这个代价。

3.2 查看:grep 定位 + 行号

配置项分散在 <html>、<head>、<body> 三段,用行号 grep 快速定位(源码目录实测):

cd /opt/littlelink/littlelink-3.11.0
grep -n 'class="theme\|<title>\|name="description"\|rel="canonical"\|avatar' index.html | head -8
10:<html class="theme-auto" lang="en"> <!-- Update `class="theme-auto"` with your preference -->
17:    <title>LittleLink</title>
21:    <meta name="description" content="Replace this with your own, this appears in search results and when sharing.">
24:    <link rel="canonical" href="https://yourwebsite.com">
76:            <img class="avatar avatar--rounded" src="images/avatar.png" srcset="images/avatar@2x.png 2x" alt="LittleLink" width="128" height="128" fetchpriority="high">

(avatar 行在默认页中首次出现于 76 行;grep 命中的其余 avatar 行为注释与占位说明,此处节选前 8 行中的关键 5 行。)

3.3 修改:sed 或编辑器,改完即生效

以「改标题」为例,在站点目录直接编辑并线上验证(实测):

cd /opt/littlelink/site
sed -i 's|<title>LittleLink</title>|<title>Quzuo Labs - 链接导航</title>|' index.html
curl -s http://localhost:8141/ | grep -n '<title>'
17:    <title>Quzuo Labs - 链接导航</title>

全程没有执行任何重启命令——这就是挂载式配置(部署指南「八、配置文件挂载」)在参数层的收益。改错想回退:cp index.html index.html.bak 先备份,或从源码目录恢复默认文件。

3.4 版本与参数事实的核对命令

版本号不靠猜,读源码目录的官方版本记录(实测):

head -4 /opt/littlelink/littlelink-3.11.0/VERSION.md
# LittleLink Version History

## Current Version: v3.11.0

四、参数总览

默认 index.html(460 行)的全部可配置项一览,行号为默认文件位置:

行号配置项载体默认值详解小节
10主题模式<html class="theme-auto">theme-auto5.1
17页面标题<title>LittleLink5.2
18站点图标<link rel="icon">images/avatar.png5.2
21搜索描述<meta name="description">占位文案5.2
24规范链接<link rel="canonical">https://yourwebsite.com5.2
27作者<meta name="author">Your Name5.2
30-31浏览器 UI 色<meta name="theme-color">#ffffff / #1212125.1/5.2
33-43社交分享卡片OG/Twitter 注释块默认注释禁用5.2
46-48字体预加载<link rel="preload"> ×3Open Sans 400/700/8005.5
51-53样式表3 个 <link rel="stylesheet">reset/style/brands5.5
56扩展品牌库注释的 brands-extended.css禁用5.7
76头像<img class="avatar avatar--rounded">128×128 圆角5.3
79/82姓名与简介<h1> / <p>LittleLink / 官方文案5.3
85按钮容器<nav class="button-stack">aria-label="Links"5.5
88-445链接按钮<a class="button button-<brand>"> ×121全部 href="#"5.4/5.6
451-453页脚<footer>隐私页 + LittleLink 链接5.8

解读:没有「隐藏参数」——上表就是 LittleLink 配置面的全部;其余文件(privacy.html、css/*、images/*)是资源而非参数。

五、核心参数分类详解

5.1 主题模式(theme-auto / theme-light / theme-dark)

首行 <html> 的 class 三选一,源码注释原文即说明书(index.html 3-10 行):

<!--
  To change the theme, change the class on the html tag below to one of:
  - theme-auto: Automatically switches based on user's system preferences
  - theme-light: Forces light theme
  - theme-dark: Forces dark theme
-->
<html class="theme-auto" lang="en">

三种取值的行为差异由 css/style.css 实现(源码实测回显):

grep -nE 'theme-light|theme-dark|theme-auto|color-scheme|prefers-color-scheme' css/style.css | head -12
205::root.theme-light {
206:	color-scheme:light;
210::root.theme-dark {
211:	color-scheme:dark;
213::root.theme-dark :focus-visible {
217::root.theme-dark body {
221::root.theme-dark a:not(.button) {
224::root.theme-dark a:not(.button):hover {
229::root.theme-auto {
230:	color-scheme:light dark;
232:@media (prefers-color-scheme:dark) {
233:	:root.theme-auto body {
取值机制适用
theme-auto(默认)color-scheme:light dark + @media (prefers-color-scheme:dark) 跟随访客系统面向公网、访客偏好不一
theme-light强制 color-scheme:light(v3.11.0 才真正实现该 class)品牌要求亮色
theme-dark强制暗色:body 背景 #121212、正文白字、非按钮链接 #4899F7夜间/暗色品牌

修改与验证(实测,改完无需重启):

sed -i 's|<html class="theme-auto"|<html class="theme-dark"|' /opt/littlelink/site/index.html
curl -s http://localhost:8141/ | grep -n 'class="theme'
10:<html class="theme-dark" lang="en"> <!-- Update `class="theme-auto"` with your preference -->

💡 说明:theme-color 两条 meta(30-31 行)与主题联动——浅色模式浏览器 UI 取 #ffffff、深色取 #121212,改主题色需同步改这两行,否则手机浏览器地址栏配色与页面脱节。

5.2 SEO 与社交分享元数据

<head> 中 6 组参数,官方在注释里直接给了推荐值:

参数行号官方建议说明
<title>1750-60 字符搜索引擎结果与标签页标题
meta description21150-160 字符搜索结果摘要,默认是占位文案必须改
link canonical24你的正式域名防重复收录;v3.11.0 修复了它曾是非法 <meta> 的 bug
meta author27你的名字作者署名
link rel=icon18换成自己的图favicon 直接复用 images/avatar.png 路径
OG/Twitter 块33-43取消注释并填写社交/IM 分享卡片

OG 块默认整段被 <!-- --> 注释禁用,启用实测(删除 36 行 <!-- 与 43 行 --> 两道围栏后线上抓取):

curl -s http://localhost:8141/ | grep -nE 'og:|twitter:card' | head -7
35:         og:url and og:image must be full absolute URLs. -->
36:    <meta property="og:type" content="website">
37:    <meta property="og:title" content="Your Name">
38:    <meta property="og:description" content="A short description of your page.">
39:    <meta property="og:url" content="https://yourwebsite.com">
40:    <meta property="og:image" content="https://yourwebsite.com/images/avatar@2x.png">
41:    <meta name="twitter:card" content="summary">

解读:启用后 6 条 meta 立即出现在页面中(行号前移说明注释围栏已移除)。两个硬性要求来自源码注释:og:url 与 og:image 必须填完整绝对 URL(相对路径社交平台不解析);og:image 推荐直接用 avatar@2x.png(256×256,满足多数平台最低尺寸)。填完后把 Your Name、yourwebsite.com 等占位值替换为你的真实值——这些是「用户内容」,本文演示环境实际填的是 Quzuo Labs - 链接导航(见 3.3 的 title 实测)。

5.3 头像与署名区

头像行(76 行)携带 6 个参数:

<img class="avatar avatar--rounded" src="images/avatar.png" srcset="images/avatar@2x.png 2x" alt="LittleLink" width="128" height="128" fetchpriority="high">
参数默认值含义
class 修饰符avatar--rounded形状三选一:--rounded 全圆 / --soft 圆角 / --none 直角
src / srcsetavatar.png / avatar@2x.png 2x1x/2x 双分辨率,Retina 屏取 256×256
width/height128/128v3.11.0 新增显式尺寸,防布局偏移(CLS)
fetchpriorityhighv3.11.0 新增,头像作为 LCP 元素优先加载

形状修饰符的实现(style.css 实测):

grep -nE 'avatar--none|avatar--rounded|avatar--soft|border-radius' css/style.css | head -8
185:   /* Modifier for no avatar rounding */
186:   .avatar--none {
187:	border-radius: 0%;
190:  /* Modifier for rounded avatar */
191:  .avatar--rounded {
192:	border-radius: 50%;
196:  .avatar--soft {
197:	border-radius: 0.5rem;   /* 8px rounded corners */

切换形状实测(--rounded → --soft,无需重启):

sed -i 's/class="avatar avatar--rounded"/class="avatar avatar--soft"/' /opt/littlelink/site/index.html
curl -s http://localhost:8141/ | grep -n 'class="avatar'
76:            <img class="avatar avatar--soft" src="images/avatar.png" srcset="images/avatar@2x.png 2x" alt="LittleLink" width="128" height="128" fetchpriority="high">

替换头像图片实测——官方占位头像 10986 字节,换成 128×128 纯色 PNG(307 字节)后响应头立即反映新大小:

curl -sI http://localhost:8141/images/avatar.png | grep -E 'HTTP|Content-Length'
HTTP/1.1 200 OK
Content-Length: 307

解读:srcset 里的 avatar@2x.png 是独立文件,换头像时 1x/2x 两张都要替换,否则高分屏仍显示旧图。署名区另有两行纯文本参数:79 行 <h1>(你的名字/品牌)与 82 行 <p>(一句话简介),直接改标签内文本即可。

5.4 按钮数据模型(核心)

一个按钮 = 一行 <a> 标签,结构拆解(以 GitHub 为例,88-445 行共 121 个同构按钮):

<a class="button button-github" href="https://github.com/sethcottle" target="_blank" rel="noopener"><img class="icon" aria-hidden="true" src="images/icons/github.svg" alt="GitHub Logo">GitHub</a>
组成参数必填说明
<a>class="button button-<brand>"是button 是基类(尺寸/形状),button-<brand> 是配色类
href是默认全部是 # 占位,上线前必须逐个替换
target="_blank"建议新标签页打开
rel="noopener"建议阻断 window.opener 引用,安全标配
<img>class="icon"是固定 1.25rem×1.25rem(20px)
src="images/icons/<brand>.svg"是必须与 images/icons/ 下 123 个官方 SVG 文件名一致,拼错即 404(见 FAQ Q2)
aria-hidden="true" + alt是图标对读屏隐藏、由文字承载语义(v3.11.0 无障碍整改项)
文本标签内文字是按钮显示文案

配色类定义在 css/brands.css(637 行、91 个 .button-* 类),实测查看 GitHub 类:

sed -n '216,220p' css/brands.css
.button-github {
	--button-text:#ffffff;
	--button-background:#000000;
	--button-border:1px solid #FFFFFF;
}

解读:每个品牌类只做一件事——给三个 CSS 变量赋值(文字色/背景色/边框),变量的消费端在 style.css 基类里(见 5.5)。因此「换一个品牌」= 同时改 class 后缀、href、src、alt 与文案五处;「删一个按钮」= 删整行 <a>;「调整顺序」= 移动整行——按钮在页面上的先后完全由源码行序决定。

5.5 布局与尺寸参数

按钮几何、容器与字体参数集中在 style.css(实测回显):

grep -nE 'width:18|min-height|font-size:1.125|font-weight:700|border-radius:0.5rem|--button' css/style.css
155:	width:18.75rem;             	/* 300px */
156: 	min-height:3rem;                /* 48px */
158:  	font-size:1.125rem;           	/* 18px */
159:  	font-weight:700;
162:  	background-color:var(--button-background,transparent);
163:	color:var(--button-text,#000000);
164:	border:var(--button-border,none);
165:	border-radius:0.5rem;
参数默认值消费关系
按钮宽度18.75rem(300px,1rem=16px)固定宽度居中,非百分比——移动端不溢出
按钮最小高3rem(48px)满足 WCAG 触控目标尺寸
字号/字重1.125rem(18px)/ 700按钮文字
圆角0.5rem(8px)与头像 --soft 同值
颜色三元组--button-background/--button-text/--button-border均带 CSS 回退值(transparent/#000000/none)——品牌类缺失时按钮仍可渲染(见 FAQ Q1)
图标尺寸.icon 1.25rem×1.25rem(style.css 176 行起)左置,文字间距由基类 padding 控制
页面容器.container/.column(style.css 10/31 行)单列居中布局
按钮堆栈<nav class="button-stack" aria-label="Links">(index.html 85 行)v3.11.0 起按钮包在语义化 nav 内;button-stack 无独立样式规则,仅作语义容器
字体Open Sans 400/700/800 三档 woff2,46-48 行 preload自托管字体,无外部请求

5.6 自定义按钮与 CSS 变量

官方品牌之外的链接(如自建站点)用「自定义 class + 三个变量」接入,无需改任何 CSS 文件——在 index.html 的 <head> 加一段 <style>,再在 nav 内加一行按钮。实测注入一个品牌色按钮(#083BDA)后的线上回显:

curl -s http://localhost:8141/ | grep -nE 'button-quzuo' 
90:  .button-quzuo {
96:<a class="button button-quzuo" href="https://www.quzuo.net" target="_blank" rel="noopener"><img class="icon" aria-hidden="true" src="images/icons/littlelink.svg" alt="Quzuo Logo">我的自托管文档站</a>

对应的 <style> 内容(写入 index.html 第 90 行处):

.button-quzuo { --button-text:#ffffff; --button-background:#083BDA; --button-border:1px solid #083BDA; }

解读:这与 5.4 的 .button-github 完全同构——自定义按钮不是「hack」,而是官方 CSS 变量机制(5.5 表)的正统用法;悬停效果(filter:brightness(90%) + 上浮 1px)由基类自动继承。图标复用官方 littlelink.svg,也可放入自有 SVG 并改 src。

5.7 Extended 扩展品牌库(brands-extended.css)

官方内置 91 个品牌类之外,社区扩展库 LittleLink Extended(sethcottle/littlelink-extended 仓库,独立维护的更多品牌)通过 index.html 56 行的注释开关接入:

<!-- LittleLink Extended Stylesheet (Optional) -->
<!-- <link rel="stylesheet" href="css/brands-extended.css"> -->

启用方法是取消注释,同时把扩展库的 brands-extended.css 与对应图标放入 site/css/、site/images/icons/。只取消注释而不放文件的实测后果(演示后已恢复):

sed -i 's|<!-- <link rel="stylesheet" href="css/brands-extended.css"> -->|<link rel="stylesheet" href="css/brands-extended.css">|' /opt/littlelink/site/index.html
curl -s http://localhost:8141/ | grep -n 'brands-extended'
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8141/css/brands-extended.css
docker compose logs --tail 1
56:    <link rel="stylesheet" href="css/brands-extended.css">
404
web-1  | 10.89.68.1 - - [02/Nov/2026:18:19:15 +0000] "GET /css/brands-extended.css HTTP/1.1" 404 153 "-" "curl/8.5.0"

解读:开关生效后页面确实引用了该样式表,但文件缺失返回 404——浏览器会忽略缺失样式表继续渲染(内置按钮样式不受影响),只有扩展品牌按钮失去配色。启用扩展库的正确顺序:先拷文件、再放开关。

5.8 privacy.html 与页脚

站点自带独立隐私页(源码注释明确建议「按你的 fork 实际情况改写它」),实测在线可访问:

curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8141/privacy.html
curl -s http://localhost:8141/privacy.html | grep -n '<title>'
200
<title>Privacy Policy | LittleLink</title>

页脚(451-453 行)默认含两个链接:privacy.html 相对链接与 littlelink.io 外链("Build your own by forking LittleLink"),可整段替换为自有版权/备案信息;privacy.html 内容本身无任何运行时开关——LittleLink 无 analytics、无 cookie,隐私页写「本站不收集数据」即符合事实。

六、生产配置模板

面向「个人/小团队链接页上线」的最小推荐配置(在默认文件基础上删改,适用于任意内存规格的静态托管场景——本组件资源占用可忽略):

<html class="theme-auto" lang="zh-CN">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>Quzuo Labs - 自托管与折腾笔记</title>
    <meta name="description" content="Quzuo Labs 的链接导航:技术文档站、GitHub、RSS 与社交账号一站直达。">
    <link rel="canonical" href="https://links.example.com">
    <meta name="theme-color" content="#ffffff" media="(prefers-color-scheme: light)">
    <meta name="theme-color" content="#121212" media="(prefers-color-scheme: dark)">
    <link rel="stylesheet" href="css/reset.css">
    <link rel="stylesheet" href="css/style.css">
    <link rel="stylesheet" href="css/brands.css">
    <style>.button-quzuo { --button-text:#ffffff; --button-background:#083BDA; --button-border:1px solid #083BDA; }</style>
  </head>
  <body>
    <div class="container"><div class="column"><main>
      <img class="avatar avatar--rounded" src="images/avatar.png" srcset="images/avatar@2x.png 2x" alt="Quzuo Labs" width="128" height="128" fetchpriority="high">
      <h1>Quzuo Labs</h1>
      <p>自托管折腾与中文技术文档。</p>
      <nav class="button-stack" aria-label="Links">
        <a class="button button-quzuo" href="https://www.quzuo.net" target="_blank" rel="noopener"><img class="icon" aria-hidden="true" src="images/icons/littlelink.svg" alt="Quzuo Logo">我的自托管文档站</a>
        <a class="button button-github" href="https://github.com/sethcottle" target="_blank" rel="noopener"><img class="icon" aria-hidden="true" src="images/icons/github.svg" alt="GitHub Logo">GitHub</a>
        <a class="button button-default" href="#" target="_blank" rel="noopener"><img class="icon" aria-hidden="true" src="images/icons/generic-rss.svg" alt="RSS Icon">RSS 订阅</a>
      </nav>
    </main></div></div>
  </body>
</html>

逐项要点:

  1. lang="zh-CN":默认是 en,中文站建议改,读屏与字体回退更准;
  2. 删除全部 121 个示例按钮,只留实际要用的——默认文件是「按钮图鉴」,生产页面留空壳按钮(href="#")会被搜索引擎收录为死链;
  3. canonical/OG 的 links.example.com 替换为真实域名(OG 块需要分享卡片时再启用,见 5.2);
  4. 按钮排序按点击优先级:主站放第一行(行序即展示序,见 5.4);
  5. 该模板文件建议纳入 git 管理:index.html 即配置,diff/review/回滚全部免费。

七、常见问题

Q1:按钮 class 写错了,页面没报错但按钮没了颜色。

实测复现:把 GitHub 按钮复制一份、class 写成 button-gitub(少个 h):

grep -c 'button-gitub' css/brands.css
curl -s http://localhost:8141/ | grep -c 'button-gitub'
0
1

定位:样式表里不存在该品牌类(命中 0),但按钮 HTML 正常输出(命中 1)——由于 5.5 表中三个 CSS 变量都带回退值(背景 transparent、文字 #000000),按钮渲染成「透明底黑字」的默认样式,不报错、不 404。解决:对照 brands.css 的 91 个类名拼写(grep -o '^\.button-[a-z0-9-]*' css/brands.css 可列全表),或按 5.6 自建变量类兜底。

Q2:图标不显示 / 按钮图片 404。

src 与 images/icons/ 下 123 个官方 SVG 文件名不一致即 404,nginx error 日志会给出缺失文件在站点根下的精确路径。完整现象、定位与修复实录见 《LittleLink Docker Compose 部署指南》「十二、常见问题」Q3。

Q3:改了 css/brands.css,页面样式一直没变。

LittleLink 镜像的 nginx 配置对 css/js/图片/SVG 统一 expires 7d(实测响应头 Cache-Control: max-age=604800,见部署指南 7.2 节),而 index.html 无缓存头——所以「HTML 改动立即可见、样式改动滞后」是缓存而非配置未生效。验证服务端是否已更新:curl -sI http://localhost:8141/css/brands.css | grep Content-Length,与磁盘文件 wc -c 比对;浏览器侧强制刷新即可。

Q4:想改按钮宽度/圆角等尺寸,但 index.html 里没有这些参数。

尺寸参数不在 HTML 而在 css/style.css 基类(5.5 表:155-165 行),直接改源文件会被下次升级覆盖。推荐做法:在 index.html 的 <style> 里覆盖,例如全站按钮加宽:.button { width:22rem; }——与 5.6 自定义按钮同一机制,升级安全。

八、参考链接