diaojiangjun

Firefly

🚀 技术架构#

静态站点生成: 基于 Astro ，提供极快的加载速度和优秀的 SEO 优化
TypeScript 支持: 完整的类型安全，提升开发体验和代码质量
响应式设计: 使用 Tailwind CSS 构建，完美适配桌面端和移动端
组件化开发: 支持 Astro、Svelte 组件，灵活可扩展

📖 配置说明#

📚 详细配置文档: 查看 Firefly使用文档获取完整的配置指南

反AI焦虑指南

Wed, 15 Apr 2026 00:00:00 GMT

AI热浪下的冷静思考：为什么大多数人都被误导了#

当下，AI话题席卷网络，各种声音都在强调：不跟上潮流，就会被淘汰。

随之而来的是大量课程推销者，他们声称：购买课程、抓住机遇，通过AI实现盈利，制作AI漫画、AI视频等内容，仿佛投资课程就能轻松获利。

但这种想法存在明显缺陷。仅凭一个AI工具，缺乏其他生产要素，就想实现盈利，这并不现实。

这些课程销售者采用的策略始终如一：就像之前宣传错过短视频红利、错过黄金投资机会一样，现在只是将宣传包装换成了AI概念。

他们会告诉你：“你错过了短视频、错过了黄金、错过了各种机会，不要再错过AI！抓住这次翻身机会，否则将永远失去！”

然后按照熟悉的套路继续：“你的认知水平不足，无法获得认知范围之外的收益！购买我的课程、会员，观看直播学习AI，否则此生再无机会！”

放你妈的屁。

但实际情况并非如此。

AI风口与普通个体无关#

鹏星想把这套忽悠人的把戏秒杀到极致，就四个大字： 与你无关 。

现在零零后会经常说：

“你们那个年代到处都是机会，改革开放时期下海经商就能赚钱，房价低廉时不买房，学历有价值时不重视读书，一辈子贫穷，这不是失败又是什么？自己不行还怪别人！！！”

换成现在的说法，同样难听：

“现在的机会更多，AI爆发、短视频兴起、黄金上涨、比特币飙升，直播带货都能盈利，你一个都没抓住，这不是失败又是什么？”

面对这种情况，卖课推销者们再次出现，鼓吹要紧跟时代，现在是站在AI风口上，是个人都能通过AI实现盈利，但这种想法过于天真，就好比一个人背井离乡去大城市上班，被人问为什么不想在这里买房，是不想吗？是没钱。那为什么赚不到钱呢？我TM…

言归正传，现在真正的问题是在于：核心关注点不是AI有多强大，而是利益如何分配？计算资源掌握在谁手中？平台和生产资料归属谁？最终利润流向何处？

你认为自己的疲惫、自己的平庸，是因为没跟上AI风口？大哥，搞笑呢？真正消耗你价值的那个系统，一直在你身后默默运作，从不出声。

深层问题是：当社会结构固化后，个人努力的效果有限。这种格局本身就限制了大多数人的上升通道。就像李白，写的诗已经流传千年了，照样无法跻身权力核心、实现政治理想。是他不够努力吗？不够优秀吗？

当时的社会如同一座坚固的金字塔，顶层牢牢掌控着通往高处的阶梯，底层的攀登者无论多么优秀，都难以逾越世代累积的鸿沟，个人的奋斗在庞大的制度面前如萤火之微。

那些每天被工作消耗、承担房贷房租、需要赡养老人抚养子女、面临降薪裁员风险的人，在时间和精力上已经被现状束缚。这些高压力的工薪阶层，往往具备不错的教育背景和认知水平。

更残酷的现实是，你获得的收入，可能连你创造价值的一小部分都不到。

分享一个私货：去做含有人际交往的事，“AI”这玩意毕竟只是一个术，“情”才是道——技术可以复制，但情感他是一个混沌体，无可替代。现在最新的吹捧的”养龙虾”(openclaw)，这玩意把人的习惯整理为一个可以蒸馏的Skill，只需要消耗token，就可以24小时不间断的干活，然后公司把人辞退，被干掉的同事不是离职了，而是变成token陪伴着你，所以token中文叫”辞员”（词元）

在国内，高端工作岗位刚刚起步，产业链升级还需要很长时间，要与欧美日韩竞争高端产业，道路依然漫长。即使成功，劳动者也未必能拿到等额收益。

此外，近年来，人才市场长期供大于求，大家互相内卷，收入被压在低位。、但这还不是重点——居民部门和企业部门，分享的也只是一小块蛋糕，你们俩在那抢来抢去，根本没什么意义。那真正的大蛋糕，去哪了？

美国总人口3~4亿，每年移居近千万，作为世界最富裕的国家之一的超级大国，居然还有流浪汉，还会冻死人，正所谓朱门酒肉臭，路有冻死骨。分配问题，不可窥探，不可名状。这一切的一切，都是结构性常态，不是靠提升个认知、买个课、会用个AI，就能整体摆脱的。

那些宣传风口的博主，本质上是在制造虚假希望，让不同阶层的人相互指责，他们从中获得流量，同时帮助既得利益者维持现状。

有人将AI描述为新一轮工业革命，声称能让所有人受益，这话纯属扯淡。

AI和蒸汽机、流水线一样，表面上推动了社会进步，但发生革新的只有效率，而不是生产关系和分配逻辑。只要资源分配的权利还掌握在既得利益者手时，AI技术的先进程度与其对劳动力的压榨效率成正比。技术飞跃式发展的同时，劳动者的工作强度也在加剧——从前工人下班后至少还有自由时光，如今却出现了下班即卧，甚至要承担过劳猝死的风险。

他们还说，AI是新时代的改革开放，遍地都是机会，这更是放屁。

改革开放初期，产业空白、市场缺口众多，确实是真正的增量时代。大家都能获利，不仅因为分配比例，更因为整体规模扩大——即使比例不变，基数增加，个人获得的份额也会增长。

现在的情况完全不同：每个领域都已饱和，平台被巨头垄断，规则早已确立。大部分利润已被瓜分，新进入者面临的不是创业机会，而是打工性质的工作。

那些宣传”抓住风口实现逆袭”的故事，很少是真正的白手起家，大多是误导性的宣传。是不是真英雄去股市走走。

AI如何使用#

那么，AI风口是否完全虚假？

也不是。AI确实有用，但使用方式很重要。

对于真正有实力的群体：真正抓住AI机会的，遵循八字原则——业务优先，工具辅助。

市场上有很多关于AI的炒作，但购买课程真的能解决问题吗？

最终人们会发现，那些需要专门学习、部署、建立工作流程的事情，普通人根本用不上。而日常高频需求，不需要追赶前沿技术，现有AI工具就足够了。

花费大量金钱和精力学习的，对普通人来说，往往是低频且无用的空中楼阁，纯粹浪费时间。

正确的做法是：如果你本身就有具体的业务领域，有实际的工作需求——处理大量数据、跟进客户服务、生产内容、完成交易。这些工作真实且紧迫，AI的介入能显著提升效率、降低成本，这才是真正的价值。

比如，原本需要100名员工，现在60名就足够，效率还翻倍，这才叫务实应用。那些展示”AI赚钱截图”的人，根本没有真正的业务，他们的业务就是让人看到他们赚钱，然后吸引你购买会员或课程。

目前AI风口最确定的受益者，不是AI本身，而是教授别人使用AI的人。真正通过AI裁员降本的企业都在低调操作，而割韭菜的人却大声宣传”抓不住风口就是失败者”。

所以，对普通人而言，AI只是一个智能助手——仅此而已。它是你不想做的工作的辅助工具，就像洗衣机一样。

洗衣机解放了双手，AI解放了部分脑力。你不会因为买了洗衣机就觉得抓住了风口，对99.9%的人来说，AI并不能带来发财或翻身的机会。

AI大潮中，学习得越慢、越谨慎，最后可能越会发现，根本不需要刻意学习，因为那是浪费时间。

企业巨头宣传的”颠覆性”功能，几个月后就会被各种应用集成，变成简单的操作功能。

现在看AI语音输入，还有颠覆性吗？不过是点击一下的操作。图像生成、视频制作也是如此，未来的功能，大公司都会为你适配，不会让你去适应技术。

不需要急着去追那些最新、最酷的东西，保持人渣态度：我用你，是给你脸了，你还让我学？反了你了！

还有一个流行说法：AI会取代很多工作，人类将失业。

实际情况并非如此：理论上AI可覆盖的岗位很多，但实际覆盖率连理论的十分之一都不到。

image-20260415151603919

到底“哪些职业会立刻被替代”，需要看两个层次：
【第一层】任务可被 AI 覆盖的技术可能性 AI 作为“通用认知工具”，最先冲击的是信息处理型任务，而不是整个职业名称本身。
【第二层】现实经济中的扩散速度真正决定短期影响的，不只是模型能力，而是产品化程度、企业部署能力、成本收益比、风险承受能力、是否容易嵌入现有流程短期看，AI 更像是“任务重组工具”；中期看，才可能变成“岗位结构重塑工具”。
三句话总结：
【1】LLM 对白领、知识型、文本型工作具有很高的理论覆盖能力。
【2】现实中的实际使用远低于这种理论能力，说明 adoption 仍滞后。
【3】AI 的短期影响更像是重塑任务，而不是立刻消灭职业。

听起来头头是道，实际都是空中楼阁。技术可行与实际应用之间存在巨大差距。

AI要在企业落地，需要数据对接、系统集成、合规审查、员工培训、容错机制，每一步都需要成本和精力。技术可行不等于企业能用。

大部分工作不仅涉及信息处理，还包括人际关系处理和物理操作。在商业金融、计算机、法律等信息密集型行业，理论覆盖率虽高，实际却相差很远。

为什么？金融不仅是运行模型，还要陪伴客户、与投资者博弈、进行判断，还有很多手动工作。AI只能替代某个小任务，不能替代整个岗位。

媒体报道”AI替代岗位”，实际上是偷换概念，将”替代任务”说成”替代岗位”。

还有责任问题至今未解决。AI出错，谁承担责任？医疗、法律、社会服务等领域，理论覆盖率不低，实际几乎为零。这些领域出问题，必须有人承担责任，法律不会将责任推给AI模型。

医疗事故判AI全责，你服吗？车祸能算AI全责吗？不可能。媒体的逻辑是“技术牛逼→岗位消失”，但现实是：技术牛逼→产品化→集成→落地工作流→组织变革→监管适配→人改变→岗位重塑。每一步，都要打折扣。

AI真正的力量在于：它会逐渐消失。

它会融入生活的每个角落，让你完全感觉不到。拍照自动修图，输入自动联想，想用餐自动下单……你不会觉得”我在使用AI”，就像使用微信不会想到”我在使用即时通讯技术”。

你能想象有人教你使用微信并收费199吗？

微信2011年出来时，全网讨论能不能替代短信，有人喊”风口抓不住就死”。结果呢？它变成了空气，你用它付钱、打车、挂号，从不会想”我要抓微信风口”。纯纯笑话。

AI的终局，就是这样。它不会站在聚光灯下，只会退到幕后，融进每一个APP、每一台电器，嵌进你的每一次操作。AI本来就应该是服务我们，改善我们的生活状态，而不是进一步的增加负担。

真正的技术革命，是让你忘记技术本身！

电的发明者不会想到，有一天我们只会关注灯光，而非电流；互联网先驱也不会料到，用户只关心内容，而非协议。AI正在重走这条路：当它好用到无法感知时，就是它最成功的时候。这不是技术的消亡，而是技术的胜利——它终于从”工具”变成了”本能”。

那些把AI架在神坛上的人，最怕AI变成”自来水”——自来水卖不上价。他们要AI保持神秘、保持焦虑，这样才能当二道贩子，一手卖恐惧，一手割韭菜。

普通人应该怎么办？

技术的价值在于其效用，而非其象征意义。将AI工具化，恰是对人的主体性的确认。那些神化AI者，实际上是在技术崇拜中迷失了实用主义的智慧。真正的进步，不是拥抱抽象的技术概念，而是在具体情境中解决真实问题。

真正能让你赚钱的，是你擅长、有信息差、家人深耕的领域——只要这个行业还存在机会。利用AI提升效率，才是正确路径。

依靠的不是追逐风口，而是你在某个领域多年积累的经验、踩过的坑、付出的学费，积累的独有经验。用AI优化，哪怕只有一点改进，也比被虚假宣传误导强。

不要东奔西走，专注于自己手中的”底牌”，那些别人不知道的信息和门道，默默努力、悄悄迭代。

事以密成，语以泄败。

AI，只是你的增效工具，不是救生稻草。

本期内容可以自由使用，如果还有博主让你焦虑、催促你买课，直接分享这篇文章即可。

自卑无眠，下一期见。

想干AI的电脑配置补充：#

应大家需求，整理3档本地AI主机具体配件清单（2026年4月行情，贴合当前硬件涨价趋势，无溢价、不踩坑，避开卖课博主忽悠，总的来说我不推荐今年买电脑，很急当我没说），普通人直接照着买就行，不用多花冤枉钱：

一、入门娱乐档（8000-10000元，普通人首选）（跑中小型AI模型、语音/轻度视频模型，够用不浪费）

CPU：AMD Ryzen 5 7600X（参考价1799元）—— 够用即可，无需高端，避免被忽悠买i9/ Ryzen 9
显卡（核心）：NVIDIA RTX 4070（12GB显存，参考价4299元）—— 本地AI模型核心，支持视频/语音模型加速，2026年价格略有回落，性价比拉满，无需追4090
内存：32GB DDR5 6000MHz（参考价3199元）—— 受2026年内存涨价潮影响，价格较去年翻倍，但32GB是本地模型运行底线，不能省
硬盘：1TB NVMe SSD（参考价899元）—— 存储AI模型文件，当前消费级SSD虽成本倒挂，但1TB刚好够用，无需盲目上2TB
主板：微星B650M-A PRO（参考价899元）—— 中端主板，完美适配CPU，性价比首选
电源：航嘉650W 金牌全模组（参考价499元）—— 稳定供电，避免因电源不足导致显卡报错
机箱+散热：普通风冷+基础机箱（合计399元）—— 无需追求颜值，够用即可

二、中度实用档（15000-18000元，轻度创作需求）

CPU：AMD Ryzen 7 7800X3D（参考价2999元）—— 多任务处理更流畅，适配中型AI模型并行运行
显卡（核心）：NVIDIA RTX 4080（16GB显存，参考价7999元）—— 视频模型渲染、大模型运行速度翻倍，2026年高端显卡因显存短缺，价格维持高位
内存：64GB DDR5 6400MHz（参考价6299元）—— 应对多模型同时运行+视频素材处理，避免卡顿
硬盘：2TB NVMe SSD（参考价1799元）—— 存储更多AI模型+视频素材，规避频繁删改麻烦
主板：华硕B760M-PLUS（参考价1299元）—— 高端中端主板，稳定性更强
电源：长城750W 金牌全模组（参考价699元）—— 适配高端显卡，稳定不翻车
机箱+散热：塔式风冷+简约机箱（合计699元）—— 散热更好，适配CPU高负载运行

三、专业进阶档（25000-35000元，专业从业者专用，普通人慎选）

CPU：AMD Ryzen 9 7950X（参考价4599元）—— 顶级消费级CPU，适配海量数据处理+多模型并行
显卡（核心）：NVIDIA RTX 4090（24GB显存，参考价15999元）—— 本地大模型+高清视频模型底线配置，2026年因AI算力需求旺盛，价格居高不下
内存：128GB DDR5 6400MHz（参考价12599元）—— 受2026年内存涨价潮影响，大容量内存价格飙升，仅适合专业从业者，普通人买了纯浪费
硬盘：4TB NVMe SSD（参考价3599元）—— 存储大量大型AI模型、高清视频素材，专业创作必备，普通人1TB都用不完
主板：华硕X670E-PLUS（参考价2999元）—— 顶级主板，完美适配顶级CPU和显卡，稳定性拉满，支撑高负载运行
电源：航嘉1000W 金牌全模组（参考价1299元）—— 适配RTX 4090高功耗需求，避免供电不足导致硬件损坏，专业配置必选
机箱+散热：240水冷+高端机箱（合计1999元）—— 应对CPU、显卡高负载发热，保障硬件长期稳定运行，无需追求颜值，实用为主

最后避坑提醒：1. 所有参考价均为2026年4月市场价，不同渠道略有浮动，优先选京东自营、天猫官方店，避免买到翻新件；2. 显卡优先选NVIDIA（对AI模型加速更友好），AMD显卡对部分本地视频、语音模型兼容性较差，别被商家忽悠；3. 普通人别碰专业进阶档，哪怕卖课博主吹得再神，你用不上就是浪费，入门档完全够用。

OpenClaw Windows 本地部署（最细保姆版）

Fri, 20 Mar 2026 00:00:00 GMT

一、安装环境要求：安装nodejs和git#

1、Git下载安装：下载地址：https://git-scm.com/install/windows #

image-20260320152054792

2、Node.js下载安装：下载地址：https://nodejs.org/zh-cn/download #

image-20260320152605463

二、OpenClaw一键安装脚本#

1.点击电脑左下角图标，输入PowerShell，出现Windows PowerShell项 , 在该选项上点击右键，选择“以管理员身份运行”#

image-20260320160230413

2、脚本命令行一键式安装部署输入：npm install -g openclaw@latest 等待安装完成即可#

image-20260320202414650

错误：解决办法#

1
优先用「HTTPS 替换 SSH」的极简方案（不用配密钥，5 秒搞定）
2
你已经装了 Git，直接在管理员 PowerShell 里执行以下两条命令，强制 Git 用 HTTPS 访问 GitHub，避开 SSH 认证：
3
# 把所有 GitHub SSH 地址替换成 HTTPS
4
git config --global url."https://github.com/".insteadOf git@github.com:
5
git config --global url."https://github.com/".insteadOf ssh://git@github.com/
6

7
# 重新安装 openclaw
8
npm install -g openclaw@latest

image-20260320172227225

3、启动openclaw完成配置：#

1.检查openclaw安装版本：openclaw -v

image-20260320202559078

2. 启动openclaw： openclaw onboard

image-20260320202656731

3. 一步一步配置openclaw相关参数

暂时先不用配置skill，先能跑起来再说其他配置

（1）提示选择yes （2）QuickStart

image-20260320202946925

（3）选择大模型类型：目前小编采用国家超算免费的1千万token，但推荐QWen/minimax, 点击确认即可（需要注册账号登录激活验证）

4、进入国家超算平台注册#

官网地址：https://www.scnet.cn/

image-20260321211605621

image-20260321212028561

image-20260321212136224

5、接入API#

接入API地址：https://api.scnet.cn/api/llm/v1

在安装好的OpenClaw设备控制台输入命令

MAC/Linxu用户打开终端操作
Windows用户管理员权限打开PowerShell操作

image-20260321213740608

image-20260321214102492

image-20260321214148076

image-20260321214328784

image-20260321214433084

image-20260321214454847

image-20260321214643600

输入模型名称

image-20260321214708729

默认回车

image-20260321214733991

模型别名留空，这个直接回车就行，不用管

image-20260321214754923

（5）选择聊天工具选项，可以接入到企业微信，后续就可以通过给企业微信机器人发消息来让他工作，这里先不选：skip for now

image-20260321215043126

（6）默认先不安装相关skill Configure skills now? (recommended)：No

Enable hooks?：Skip for now

Gateway service already installed：Restart

image-20260321215207093

这个时候会自动打开另外一个cmd窗口

image-20260321215529371

**安装完后，就会自动访问：http://127.0.0.1:18789/chat ** ，就可以打开聊天界面对话让它开始工作。

image-20260321215930994

【保姆级多版本】Windows 安装JDK

Fri, 09 Jan 2026 00:00:00 GMT

1. 下载 JDK#

**【包含25、21、17、11、8】Oracle JDK：**https://pan.baidu.com/s/1lfmelC17IncuE-VUoE1Xog?pwd=pyxh 提取码: pyxh

这里以 JDK 17 为例，其他版本安装方式一样。

首先到官网找到需要版本的 JDK 压缩包下载。
选择 x64 Compressed Archive 点击下载链接即可开始下载，有的版本可能需要登录 Oracle 帐号才可以下载，注册一个就可以了。

image-20260109153614934

下载完成后将其解压，将其文件夹命名为 jdk17【小编没有重命名，你们操作可以】，解压出来的结构如图：

image-20260109153845597

2. 配环境变量#

右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”

image-20260108200743789

当只存在一个 JDK 时，Windows 只需要在环境变量中配置 JAVA_HOME，变量值：自己的 JDK 的安装路径（参考上面的安装教程），编辑好后点击确定。

image-20260109185203646

找到系统变量 path 点击编辑：

image-20260109185545257

编辑好后点击确定，暂时不要点击X号关闭。

3. 测试JDK#

输入 win+r（win键就是四个方块的那个），输入cmd，按回车。

image-20260109185824726

输入命令 java -version，按回车。如果出现以下页面，就表示安装成功。

image-20260109190037817

4. 多版本JDK配置#

首先多个 JDK 的配置方式大同小异。这里假设电脑上下载了 JDK 11 和 JDK 17 两个版本，他们的安装路径分别为 D:\jdk-11.0.11\jdk-11.0.11 和 D:\jdk-17.0.7。

操作步骤主要分为四步：

增加一个名字叫 JAVA11_HOME 的环境变量，使其指向目录 D:\jdk-11.0.11\jdk-11.0.11
增加一个名字叫 JAVA17_HOME 的环境变量，使其指向目录 D:\jdk-17.0.7
修改原来的 JAVA_HOME（没有的话就新增一个），使其值指向你想使用的 JDK 版本，比如我想使用 JDK 17，那就设置其值为 %JAVA_HOME17%
系统变量 Path 中的 bin 和 jre/bin 的目录，则完全不需要去动，因为我们在之前已经设置为%JAVA_HOME%\bin和%JAVA_HOME%\jre\bin

image-20260109191242682

验证是否成功

最后保存环境变量配置，然后打开一个新的命令行窗口输入 java --version 即可看到当前使用的 java 版本了。

image-20260109191658450

5.【拓展一】为什么没有 JRE 文件夹#

一、先说明：为什么 JDK1.8 之后没有 JRE 文件夹了？（核心原因）#

这个不是安装包残缺、不是安装失败，而是 Oracle 官方的刻意调整，从 JDK 9 开始彻底移除，JDK 1.8 是「过渡期」：

JDK 1.8 早期版本（比如 jdk1.8.0_101 之前）：安装后自带jre文件夹；
JDK 1.8 后期版本（比如 jdk1.8.0_200 及以后）：安装后无 JRE 文件夹；
JDK 9 / 10 / 11 / 17 等更高版本：完全取消了内置 JRE。

二、官方移除 JRE 的核心目的#

JRE（Java 运行环境）本质是 JDK 的「子集」，JDK 中已经包含了 JRE 运行所需的所有核心文件，官方为了节省安装包体积、精简目录结构、统一运行 / 开发环境，就不再单独打包 JRE 了，JRE 的功能完全可以由 JDK 本身提供。

三、这个情况对开发的「具体影响」（关心的重点）#

没有 JRE 文件夹，对 Java 代码编写、编译（javac）、本地调试运行（java）基本无影响，但会在这些开发场景下直接报错 / 卡壳，也是你能明显感知到的影响，按出现频率排序：

✔ 影响 1：IDE 配置时提示「找不到 JRE 路径」#

Eclipse/MyEclipse/IDEA 配置 JDK 的时候，部分版本会默认去JAVA_HOME/jre目录读取运行环境，找不到就会标红、提示「JRE 缺失」，甚至无法创建 Java 项目；
IDEA 还好兼容性强，Eclipse 对这个问题最敏感，几乎必报错。

✔ 影响 2：项目打包 / 部署时报错#

用 maven/gradle 打包 Java 项目（比如打 jar 包、war 包）时，部分插件会默认读取JAVA_HOME/jre，找不到则打包失败；
把项目部署到 Tomcat/Jetty 等容器时，容器如果配置了关联 JDK 的 JRE 路径，会启动失败。

✔ 影响 3：第三方工具 / 软件关联 Java 环境时失败#

比如你开发中用到的：NodeJS 相关插件、Jenkins、Maven 独立运行、Android Studio 等，部分工具会要求指定 JRE 路径，无 JRE 文件夹则配置失败。

✔ 无影响的场景（放心）#

命令行直接编译运行：javac Hello.java + java Hello 完全正常，JDK 本身就能提供运行环境；
IDEA 中正常开发 SpringBoot/SpringCloud 项目：新版本 IDEA 会自动识别 JDK 内置的 JRE，无需手动配置；
本地运行已编译的 class 文件 /jar 包：无任何影响。

四、解决方案（生成 JRE 文件夹）#

核心原则：不用重新下载 JDK、不用重装，直接用 JDK 自带的命令生成官方合规的 JRE 文件夹，生成的 JRE 和原版完全一致，完美解决所有开发问题，推荐所有人用第一种方法，最简单高效！
前提：你的 JDK 安装目录是确定的，比如你的目录 D:\jdk-11.0.11\jdk-11.0.11（先记住这个路径，下面全程用这个格式举例）

JRE文件夹生成

1
// 执行生成 JRE 的核心命令（一行搞定，回车后等待 3-5 秒，无报错即成功）：
2
bin\jlink.exe --module-path jmods --add-modules java.desktop --output jre

image-20260109193517177

现在就大功告成了，JDK17同样可以使用该命令生成对应的 jre文件夹,虽然小编个人认为对于现在新的项目开发大多都会采用jdk17及以上的版本，老项目也是采用jdk1.8，开发工具如果是自己学习我想应该会使用IntelliJ IDEA，所以这个jre不配置是完全没有关系的。

【保姆级】Node.js 最新安装教程，附环境变量配置

Thu, 08 Jan 2026 00:00:00 GMT

零基础安装 Node.js（Windows）#

你只要照做：下载 -> 安装 -> 配环境变量 -> 验证
看不懂没关系：每张图就是上一步文字的结果

1. 下载安装包#

打开官网下载页：官网下载传送门
选择你的系统版本，点击 Windows 安装包（.msi） 下载

image-20260108180846526

想下载旧版本：在页面里找到“之前的版本/历史版本”入口

image-20260108181020150

2. 安装程序#

双击下载好的 .msi，一路点 Next
到选择安装位置这一步：建议不要装在 C 盘（选 D/E 盘即可）、建议目录中不要包含中文、空格以及特殊字符

image-20260108181532446

这一步保持默认即可

image-20260108181854814

继续 Next

image-20260108181927911

点击 Install 开始安装

image-20260108182108763

点击 Finish 完成安装

image-20260108182250603

验证是否安装成功

按 Win + R，输入 cmd 回车
输入：node -v 回车，再输入：npm -v 回车

image-20260108182516094

能看到版本号，说明安装成功。

3. 环境配置（照做即可）#

3.1 新建两个文件夹#

打开你的 Node.js 安装目录，新建两个文件夹：node_cache、node_global

image-20260108194630810

进入这两个文件夹，复制它们的“文件夹地址”（后面要用）

image-20260108195034386

3.2 设置 npm 的全局目录和缓存#

按 Win + X -> 选择 终端（管理员），分别执行下面两条命令（把路径换成你自己的）

image-20260407214853516

修改npm配置

1
//如果出现这个请先运行 npm : 无法加载文件 D:\nodejs\npm.ps1，因为在此系统上禁止运行脚本。xxxxxxx
2
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
3

4
// 修改 npm 全局安装包的默认路径
5
npm config set prefix "D:\nodejs\node_global"
6

7
// 查看是否修改成功
8
npm config get prefix
9

10
// 修改 npm 全局缓存路径
11
npm config set cache "D:\nodejs\node_cache"
12

13
// 查看是否修改成功
14
npm config get cache

image-20260108200309018

注意：一定要用“管理员”打开终端，否则可能失败。

拓充：

prefix设置 npm 全局安装包的存放目录，当使用npm install -g package-name安装全局包的时候，会默认安装到此目录,从而统一管理Node.js相关文件。

cache设置 npm 下载缓存的存放目录，将下载的包先缓存到这里，下次安装同版本时直接使用缓存，从而节省空间，加快安装速度。

为什么要改这个路径？（核心价值）
默认情况下，npm 的全局路径在系统盘（Windows 是 C:\Users\你的用户名\AppData\Roaming\npm），修改它的核心好处：

避免 C 盘臃肿：全局安装的包（如 webpack、node-sass）体积大，长期使用会占满 C 盘空间，转移到 D 盘能减轻系统盘压力；

方便管理：把 Node 相关的运行文件集中放到 D:\nodejs 目录下，便于统一备份、迁移或卸载；

权限问题：默认路径可能需要管理员权限才能写入，自定义路径可避免安装包时出现「权限不足」的报错。

3.3 配环境变量#

右键“此电脑” -> “属性” -> “高级系统设置” -> “环境变量”

image-20260108200743789

点击“新建”，创建系统变量 NODE_PATH

变量值：node_global文件夹的路径 + \node_modules

image-20260108201134259

在“用户变量”里编辑 Path

把默认的 ...AppData\Roaming\npm 改成你的 node_global 路径

image-20260108201833479

在“系统变量”里选择 Path -> “编辑” -> “新建” -> 输入：%NODE_PATH%
一路点“确定”保存，关闭所有窗口后，重新打开 终端/命令行（这一步很关键）

image-20260108203307584

4. 测试（配置有没有生效）#

按 Win + X -> 选择 终端（管理员）
执行下面命令（安装一个全局包做验证）

测试

1
npm install express -g    // -g代表全局安装

看到安装成功的输出，就说明配置成功。

image-20260108203503593

5. (推荐)设置 npm 国内镜像（下载更快）#

如果你发现 npm install 很慢，再做这一步：

按 Win + X -> 选择 终端（管理员），执行：

npm 国内镜像

1
npm config set registry https://mirrors.cloud.tencent.com/npm/  # 腾讯云
2
npm config set registry https://registry.npmmirror.com          # 淘宝源

验证镜像源，执行以下命令检查当前镜像：

验证

1
npm config get registry

显示自己设置的镜像源，就表示成功。

image-20260108203926091

到这里，你的 Node.js 安装与环境变量配置就完成了。

6. 拓展：常见问题#

6.1 pnpm的安装#

现在前端主流项目基本都用 pnpm，我们可以直接把pnpm看作是npm的升级版本
按 Win + X -> 选择 终端（管理员），执行：

pnpm 安装

1
// 方式 1：通过 npm 全局安装（最方便，你已安装 npm）
2
npm install -g pnpm
3

4
// 方式 2：通过官方脚本安装（适用于无 npm 环境）
5
//如果你的环境没有 npm，可执行官方脚本：
6
//（该脚本会自动下载并配置 pnpm，Windows 需用 PowerShell 执行）
7
iwr https://get.pnpm.io/install.ps1 -useb | iex

安装完成后，pnpm 会被放到你配置的 D:\nodejs\node_global\node_modules 目录下（和 npm 全局包同路径）。

image-20260108205058234

验证 pnpm 是否安装成功

重启终端（确保环境变量生效），执行：

检验

1
pnpm -v

image-20260108205412415

6.2 权限不足 (EPERM)#

在使用的时候报错较多，显示EPERM错误，这个错误通常是因为文件/文件夹权限问题导致的，错误示例如下：

image-20260108205637440

解决方案：#

键盘【Win+X】，打开终端管理员，重新尝试。如果不行，需要修改Node.js安装目录权限，修改npm缓存目录权限，仍旧在终端管理员执行下述命令。

修改权限

1
// 修改Node.js安装目录权限
2
icacls "你的Node.js安装目录" /grant Users:F /T
3

4
// 修改npm缓存目录权限
5
icacls "你的node_global目录" /grant Users:F /T
6
icacls "你的node_cache目录" /grant Users:F /T

可以通过以下指令，获取你对应的目录

npm缓存目录

1
npm config get prefix
2
npm config get cache

示例如下

Terminal window

1
icacls "D:\nodejs" /grant Users:F /T
2
icacls "D:\nodejs\node_global" /grant Users:F /T
3
icacls "D:\nodejs\node_cache" /grant Users:F /T

为什么需要设置这些权限？#

Windows 默认对非系统盘目录的权限较严格，若不授权：

执行 npm install -g 时，会提示 EPERM: operation not permitted（权限不足）；
运行 pnpm 安装包时，会提示「无法写入缓存 / 全局目录」；
Node.js 运行时读取依赖包可能提示「访问被拒绝」。

补充：权限回收 / 修正（若误操作）#

如果想收回过度授权的权限（比如只需要「读取 + 写入」而非完全控制），可执行：

1
# 授予「读取+写入」权限（够用且更安全）
2
icacls "D:\nodejs" /grant Users:RW /T

参数说明：R=读取、W=写入、F=完全控制，根据需求选择。

验证权限是否设置成功#

打开文件资源管理器，找到 D:\nodejs；
右键该文件夹 →「属性」→「安全」选项卡；
在「组或用户名」中找到「Users」，点击「编辑」；
查看「Users 的权限」，如果「完全控制」勾选了「允许」，说明设置成功。

关于SPring Boot文件上传的两种方式

Fri, 19 Dec 2025 00:00:00 GMT

关于SPring Boot文件上传的两种方式#

传统方式--->本地上传#

概述场景#

文件上传，是程序开发中必须会使用到一个功能,比如:

添加商品,用户头像,文章封面等需求

富文本编辑（插件文件上传）

文件上传原理是什么？#

为什么要实现文件上传？ ---> 就是为了要共享资源，大家都可以在你的平台上看到上传的文件，一句话概括：就是把自己电脑上的文件通过程序上传到服务器的过程！

image-20230716111902733

其实就是一句话:把用户的文件通过javaio流程复制到服务器的过程，称之为文件上传。

使用SpringBoot如何实现文件上传呢？#

使用spring boot完成的本地文件上传

1.1、实现步骤#

1.1.1、搭建一个spring boot工程#

1
<dependencies>
2
        <dependency>
3
            <groupId>org.springframework.boot</groupId>
4
            <artifactId>spring-boot-starter-web</artifactId>
5
        </dependency>
6
        <dependency>
7
            <groupId>org.springframework.boot</groupId>
8
            <artifactId>spring-boot-starter-freemarker</artifactId>
9
        </dependency>
10
    </dependencies>

1.1.2、准备一个文件上传的页面#

在resources/templates/upload.html

1
server:
2
  port: 3333
3

4
spring:
5
  freemarker:
6
    suffix: .html
7
    cache: false

1.1.3、实现后台的文件上传#

定义文件上传的server

1
package com.nacl.server;
2

3
import org.springframework.stereotype.Service;
4
import org.springframework.web.multipart.MultipartFile;
5

6
import java.io.File;
7
import java.io.IOException;
8

9
/**
10
 * @author HAOYANG
11
 * @create 2023-07-16 11:41
12
 */
13
@Service
14
public class UploadServe {
15

16
    /**
17
     * MultipartFile这个对象是springHvc提供的文件上传的接受的类。
18
     * 它的底层自动会去和HttpServletRequest request中的request.getInputstream()融合
19
     * 从而达到文件上传的效果。也就是告诉你一个道理:
20
     * 文件上传威层原理是:request.getinputstream()
21
     * @param multipartFile
22
     * @param dir
23
     * @return
24
     */
25
    public String uploadImg(MultipartFile multipartFile,String dir){
26
        //1. 指定文件上传的目录
27
        File targetFile = new File("D://usr//local//upload/"+dir);
28
        try {
29
            if (!targetFile.exists())targetFile.mkdirs();
30
            //2. 文件上传的文件名
31
            File targetFileName = new File(targetFile,"aaa.png");
32
            //2. 文件上传到指定的目录
33
            multipartFile.transferTo(targetFileName);
34
            return "ok";
35
        } catch (IOException e) {
36
            e.printStackTrace();
37
            return "fail";
38
        }
39
    }
40
}

展开收起

定义文件上传的controller

1
package com.nacl.controller;
2

3
import com.nacl.server.UploadServe;
4
import org.springframework.beans.factory.annotation.Autowired;
5
import org.springframework.stereotype.Controller;
6
import org.springframework.web.bind.annotation.PostMapping;
7
import org.springframework.web.bind.annotation.RequestParam;
8
import org.springframework.web.bind.annotation.ResponseBody;
9
import org.springframework.web.multipart.MultipartFile;
10

11
import javax.servlet.http.HttpServletRequest;
12

13
/**
14
 * @author HAOYANG
15
 * @create 2023-07-16 11:40
16
 */
17
@Controller
18
public class UploadController {
19

20
    @Autowired
21
    UploadServe uploadServe;
22
    /**
23
     * 文件上传具体实现
24
     * @param multipartFile
25
     * @param request
26
     * @return
27
     */
28
    @PostMapping("/upload/file")
29
    @ResponseBody
30
    public String upload(@RequestParam("file")MultipartFile multipartFile, HttpServletRequest request){
31
        if (multipartFile.isEmpty()){
32
            return "文件有误";
33
        }
34
        //原文件大小
35
        long size = multipartFile.getSize();
36
        //原文件名
37
        String originalFilename = multipartFile.getOriginalFilename();
38
        //原文件类型
39
        String contentType = multipartFile.getContentType();
40
        //1:获取用户指定的文件夹。问这个文件夹为什么要从页面上传递过来呢?
41
        //原因是:傲隔离，不司业务，不同文件放在不同的目录中
42
        String dir = request.getParameter("dir");
43
        return uploadServe.uploadImg(multipartFile,dir);
44
    }
45
}

展开收起

定义文件上传的html

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8">
5
    <title>文件上传</title>
6
</head>
7
<body>
8
<h1>文件上传</h1>
9
<form action="/upload/file" enctype="multipart/form-data" method="post">
10
    <input name="dir" value="bbs">
11
    <input name="file" type="file">
12
    <input type="submit" value="文件上传">
13
</form>
14
</body>
15
</html>

展开收起

修改一下

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8">
5
    <title>文件上传</title>
6
</head>
7
<body>
8
<h1>文件上传</h1>
9
<form action="/upload/file" id="uploadform" enctype="multipart/form-data" method="post">
10
    <input name="dir" value="bbs">
11
    <input name="file" onchange="toupload()" type="file">
12

13
</form>
14

15
<script>
16
    function toupload() {
17
        document.getElementById("uploadform").submit();
18
    }
19
</script>
20
</body>
21
</html>

展开收起

运行项目就可以看到如下效果：

image-20230716120708076

springmvc中文件上传给提供了包装对象MultipartFile原理如下：

image-20230716120252803

通过MultipartFile我吗很清楚的看到，文件上传已经被服务器接收。

但是会产生一个临时目录，这个目录是可以去配置

image-20230716122354538

文件上传不会直接上传真是的目录，它一定要经过一个临时目录的中转以后，才会上传到真是目录。作用:

1、防止上传出现网络断开，或者用户上传直接刷新或者取消。因为如果用户的网络断开或者取消，就造成大量的垃圾文件

2、保证真实目录上传的文件一定是有效的。
文件上传的大小:也可以进行配置的

文件上传的类型:也是进行配置的

1
server:
2
  port: 3333
3

4
spring:
5
  freemarker:
6
    suffix: .html
7
    cache: false
8
  servlet:
9
    multipart:
10
      enabled: true
11
      # 单个文件上传大小  默认是1MB
12
      max-file-size: 10MB
13
      # 设置总上传的数据大小
14
      max-request-size: 100MB
15
      # 当文件达到多少大小时，进行磁盘写入
16
      file-size-threshold: 20MB
17
      # 设置临时目录
18
      location: D://usr//local//temp

展开收起

1.1.4、指定文件上传的目录#

配置spring boot静态资源存储服务，将上传的文件放入指定的目录中

1
package com.nacl.server;
2

3
import org.springframework.stereotype.Service;
4
import org.springframework.web.multipart.MultipartFile;
5

6
import java.io.File;
7
import java.io.IOException;
8
import java.text.SimpleDateFormat;
9
import java.util.Date;
10
import java.util.UUID;
11

12
/**
13
 * @author HAOYANG
14
 * @create 2023-07-16 11:41
15
 */
16
@Service
17
public class UploadServe {
18

19
    /**
20
     * MultipartFile这个对象是springHvc提供的文件上传的接受的类。
21
     * 它的底层自动会去和HttpServletRequest request中的request.getInputstream()融合
22
     * 从而达到文件上传的效果。也就是告诉你一个道理:
23
     * 文件上传威层原理是:request.getinputstream()
24
     * @param multipartFile
25
     * @param dir
26
     * @return
27
     */
28
    public String uploadImg(MultipartFile multipartFile,String dir){
29
        try {
30
            //1.原文件名
31
            String oldFilename = multipartFile.getOriginalFilename(); // 上传的文件：aaa.png
32
            // 2. 截取文件名的后缀
33
            String imgSuffix = oldFilename.substring(oldFilename.lastIndexOf("."));//拿到 .png
34
            //3. 生成唯一的文件名  不能用中文名，统一用英文
35
            String newFileName = UUID.randomUUID().toString()+imgSuffix;//将aaa.png改写成Sdjksdj532XXX.png   Sdjksdj532XXX--->这个是随意的
36
            //4. 日期目录
37
            SimpleDateFormat dateFormat = new SimpleDateFormat("yyy/MM/dd");
38
            String datePath = dateFormat.format(new Date());//日期目录：2023/7/16
39
            //5. 原文件上传以后的目录
40
            File targetPath = new File("D://usr//local//upload/"+dir,datePath);//生成一个最终的目录：D:/usr/local/upload/2023/7/16
41
            if (!targetPath.exists())targetPath.mkdirs();//如果目录不存在：D:/usr/local/upload/2023/7/16   递归创建
42
            //6. 指定文件上传以后的服务器的完整的文件名
43
            File targetFileName = new File(targetPath,newFileName);// 文件上传以后在服务器上最终文件名和目录是://如果目录不存在：D:/usr/local/upload/2023/7/16/Sdjksdj532XXX.png
44
            //7. 文件上传到指定的目录
45
            multipartFile.transferTo(targetFileName);//将用户选择的aa.png上传到D:/usr/local/upload/2023/7/16/Sdjksdj532XXX.png
46
            return "ok";
47
        } catch (IOException e) {
48
            e.printStackTrace();
49
            return "fail";
50
        }
51
    }
52
}

展开收起

效果图：

image-20230716124731824

1.1.5、通过http请求访问资源#

springboot如果去指定任意目录作为的资源的访问目录?

springboot有一个目录： static这个目录其实就是静态资源目录，这个目录下面的文件是可以通过http直接问题的。但是程序话一般打成jar包，我们没办法去文件写入到这个static下，所以springboot提供静态资源目录的额外的映射机制，就是静态资源服务映射。它就类似于: nginx的静态资源映射

配置静态资源服务映射：

1
package com.nacl.config;
2

3
import org.springframework.context.annotation.Configuration;
4
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
5
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
6

7
/**
8
 * @author HAOYANG
9
 * @create 2023-07-16 13:06
10
 */
11
@Configuration
12
public class WebMvcConfiguration implements WebMvcConfigurer {
13

14
    //这个就是springboot/springMvc让程序开发者去配置文件上传的额外的静态资源服务的配置
15
    @Override
16
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
17
        registry.addResourceHandler("/uploadimg").addResourceLocations("file:D://usr//local//upload");
18
    }
19
}

展开收起

核心代码分析：

1
registry.addResourceHandler("访问路径").addResourceLocations("上传资源路径");
2
 registry.addResourceHandler("/uploadimg/**").addResourceLocations("file:D://usr//local//upload//");

这个时候自己把aaa.png文件上传到D://usr//local//upload下，就可以通过http://localhost:3333/uploadimg/aaa.png，进行访问了

完整代码：

image-20230716134229788

定义文件映射的WebMvcConfiguration

1
package com.nacl.config;
2

3
import org.springframework.beans.factory.annotation.Value;
4
import org.springframework.context.annotation.Configuration;
5
import org.springframework.web.servlet.config.annotation.ResourceHandlerRegistry;
6
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;
7

8
/**
9
 * @author HAOYANG
10
 * @create 2023-07-16 13:06
11
 */
12
@Configuration
13
public class WebMvcConfiguration implements WebMvcConfigurer {
14

15
    @Value("${file.staticPatternPath}")
16
    private String staticPatternPath;
17
    @Value("${file.uploadFolder}")
18
    private String uploadFolder;
19
    //这个就是springboot/springMvc让程序开发者去配置文件上传的额外的静态资源服务的配置
20
    @Override
21
    public void addResourceHandlers(ResourceHandlerRegistry registry) {
22
        registry.addResourceHandler(staticPatternPath).addResourceLocations("file:"+uploadFolder);
23
    }
24
}

展开收起

controller

1
package com.nacl.controller;
2

3
import com.nacl.server.UploadServe;
4
import org.springframework.beans.factory.annotation.Autowired;
5
import org.springframework.stereotype.Controller;
6
import org.springframework.web.bind.annotation.PostMapping;
7
import org.springframework.web.bind.annotation.RequestParam;
8
import org.springframework.web.bind.annotation.ResponseBody;
9
import org.springframework.web.multipart.MultipartFile;
10

11
import javax.servlet.http.HttpServletRequest;
12

13
/**
14
 * @author HAOYANG
15
 * @create 2023-07-16 11:40
16
 */
17
@Controller
18
public class UploadController {
19

20
    @Autowired
21
    UploadServe uploadServe;
22
    /**
23
     * 文件上传具体实现
24
     * @param multipartFile
25
     * @param request
26
     * @return
27
     */
28
    @PostMapping("/upload/file")
29
    @ResponseBody
30
    public String upload(@RequestParam("file")MultipartFile multipartFile, HttpServletRequest request){
31
        if (multipartFile.isEmpty()){
32
            return "文件有误";
33
        }
34
        //原文件大小
35
        long size = multipartFile.getSize();
36
        //原文件名
37
        String originalFilename = multipartFile.getOriginalFilename();
38
        //原文件类型
39
        String contentType = multipartFile.getContentType();
40
        //1:获取用户指定的文件夹。问这个文件夹为什么要从页面上传递过来呢?
41
        //原因是:傲隔离，不司业务，不同文件放在不同的目录中
42
        String dir = request.getParameter("dir");
43
        return uploadServe.uploadImg(multipartFile,dir);
44
    }
45
}

展开收起

service

1
package com.nacl.server;
2

3
import org.springframework.beans.factory.annotation.Value;
4
import org.springframework.stereotype.Service;
5
import org.springframework.web.multipart.MultipartFile;
6

7
import java.io.File;
8
import java.io.IOException;
9
import java.text.SimpleDateFormat;
10
import java.util.Date;
11
import java.util.UUID;
12

13
/**
14
 * @author HAOYANG
15
 * @create 2023-07-16 11:41
16
 */
17
@Service
18
public class UploadServe {
19

20
    @Value("${file.uploadFolder}")
21
    private String uploadFolder;
22
    @Value("${file.staticpath}")
23
    private String staticpath;
24
    /**
25
     * MultipartFile这个对象是springHvc提供的文件上传的接受的类。
26
     * 它的底层自动会去和HttpServletRequest request中的request.getInputstream()融合
27
     * 从而达到文件上传的效果。也就是告诉你一个道理:
28
     * 文件上传威层原理是:request.getinputstream()
29
     * @param multipartFile
30
     * @param dir
31
     * @return
32
     */
33
    public String uploadImg(MultipartFile multipartFile,String dir){
34
        try {
35
            //1.原文件名
36
            String oldFilename = multipartFile.getOriginalFilename(); // 上传的文件：aaa.png
37
            // 2. 截取文件名的后缀
38
            String imgSuffix = oldFilename.substring(oldFilename.lastIndexOf("."));//拿到 .png
39
            //3. 生成唯一的文件名  不能用中文名，统一用英文
40
            String newFileName = UUID.randomUUID().toString()+imgSuffix;//将aaa.png改写成Sdjksdj532XXX.png   Sdjksdj532XXX--->这个是随意的
41
            //4. 日期目录
42
            SimpleDateFormat dateFormat = new SimpleDateFormat("yyy/MM/dd");
43
            String datePath = dateFormat.format(new Date());//日期目录：2023/7/16
44
            //5. 原文件上传以后的目录
45
            String servepath = uploadFolder;//D://usr//local//upload/
46
            File targetPath = new File(servepath+dir,datePath);//生成一个最终的目录：D:/usr/local/upload/2023/7/16
47
            if (!targetPath.exists())targetPath.mkdirs();//如果目录不存在：D:/usr/local/upload/2023/7/16   递归创建
48
            //6. 指定文件上传以后的服务器的完整的文件名
49
            File targetFileName = new File(targetPath,newFileName);// 文件上传以后在服务器上最终文件名和目录是://如果目录不存在：D:/usr/local/upload/2023/7/16/Sdjksdj532XXX.png
50
            //7. 文件上传到指定的目录
51
            multipartFile.transferTo(targetFileName);//将用户选择的aa.png上传到D:/usr/local/upload/2023/7/16/Sdjksdj532XXX.png
52
            // 可以访问的路径要返回页面
53
            //http://localhost:3333/uploadimg/bbs/2023/7/16/Sdjksdj532XXX.png
54
            String filename = dir+"/"+datePath+"/"+newFileName;
55
            return staticpath+"/uploadimg/"+filename;
56
        } catch (IOException e) {
57
            e.printStackTrace();
58
            return "fail";
59
        }
60
    }
61
}

展开收起

application-dev.yml

1
# 本机配置
2
file:
3
  staticpath: http://localhost:3333
4
  staticPatternPath: /uploadimg/**
5
  uploadFolder: D:/usr/local/upload/

application.yml

1
server:
2
  port: 3333
3

4
spring:
5
  freemarker:
6
    suffix: .html
7
    cache: false
8
  profiles:
9
    active: dev
10
  servlet:
11
    multipart:
12
      enabled: true
13
      # 单个文件上传大小  默认是1MB
14
      max-file-size: 10MB
15
      # 设置总上传的数据大小
16
      max-request-size: 100MB
17
      # 当文件达到多少大小时，进行磁盘写入
18
      file-size-threshold: 20MB
19
      # 设置临时目录
20
      location: D://usr//local//temp

展开收起

application-prod.yml

1
# 服务器配置
2
file:
3
  staticpath: https://www.xxxxx.com
4
  staticPatternPath: /uploadimg/**
5
  uploadFolder: /www/upload/

实现效果：

image-20230716134756917

image-20230716134813474

1.1.6、对文件上传的思考和优化与控制#

比如文件的格式
比如文件的大小

在application.yml可以配置
比如文件的重命名

简略使用UUID.randomUUID().toString()随机生成一个

比如文件的目录分类

前端没有传入目录名称，后端有一个天然的目录--->日期目录，用指定的文件目录+日期目录

1
SimpleDateFormat dateFormat = new SimpleDateFormat("yyy/MM/dd");
2
String datePath = dateFormat.format(new Date());//日期目录：2023/7/16
3
//5. 原文件上传以后的目录
4
String servepath = uploadFolder;//D://usr//local//upload/
5
File targetPath = new File(servepath+dir,datePath);//生成一个最终的目录：D:/usr/local/upload/2023/7/16
6
if (!targetPath.exists())targetPath.mkdirs();//如果目录不存在：  D:/usr/local/upload/2023/7/16  递归创建

对service进行封装

1
package com.nacl.server;
2

3
import org.springframework.beans.factory.annotation.Value;
4
import org.springframework.stereotype.Service;
5
import org.springframework.web.multipart.MultipartFile;
6

7
import java.io.File;
8
import java.io.IOException;
9
import java.text.SimpleDateFormat;
10
import java.util.Date;
11
import java.util.HashMap;
12
import java.util.Map;
13
import java.util.UUID;
14

15
/**
16
 * @author HAOYANG
17
 * @create 2023-07-16 11:41
18
 */
19
@Service
20
public class UploadServe {
21

22
    @Value("${file.uploadFolder}")
23
    private String uploadFolder;
24
    @Value("${file.staticpath}")
25
    private String staticpath;
26
    /**
27
     * MultipartFile这个对象是springHvc提供的文件上传的接受的类。
28
     * 它的底层自动会去和HttpServletRequest request中的request.getInputstream()融合
29
     * 从而达到文件上传的效果。也就是告诉你一个道理:
30
     * 文件上传威层原理是:request.getinputstream()
31
     * @param multipartFile
32
     * @param dir
33
     * @return
34
     */
35
    public Map<String,Object> uploadImg(MultipartFile multipartFile, String dir){
36
        try {
37
            //1.原文件名
38
            String oldFilename = multipartFile.getOriginalFilename(); // 上传的文件：aaa.png
39
            // 2. 截取文件名的后缀
40
            String imgSuffix = oldFilename.substring(oldFilename.lastIndexOf("."));//拿到 .png
41
            //3. 生成唯一的文件名  不能用中文名，统一用英文
42
            String newFileName = UUID.randomUUID().toString()+imgSuffix;//将aaa.png改写成Sdjksdj532XXX.png   Sdjksdj532XXX--->这个是随意的
43
            //4. 日期目录
44
            SimpleDateFormat dateFormat = new SimpleDateFormat("yyy/MM/dd");
45
            String datePath = dateFormat.format(new Date());//日期目录：2023/7/16
46
            //5. 原文件上传以后的目录
47
            String servepath = uploadFolder;//D://usr//local//upload/
48
            File targetPath = new File(servepath+dir,datePath);//生成一个最终的目录：D:/usr/local/upload/2023/7/16
49
            if (!targetPath.exists())targetPath.mkdirs();//如果目录不存在：D:/usr/local/upload/2023/7/16   递归创建
50
            //6. 指定文件上传以后的服务器的完整的文件名
51
            File targetFileName = new File(targetPath,newFileName);// 文件上传以后在服务器上最终文件名和目录是://如果目录不存在：D:/usr/local/upload/2023/7/16/Sdjksdj532XXX.png
52
            //7. 文件上传到指定的目录
53
            multipartFile.transferTo(targetFileName);//将用户选择的aa.png上传到D:/usr/local/upload/2023/7/16/Sdjksdj532XXX.png
54
            // 可以访问的路径要返回页面
55
            //http://localhost:3333/uploadimg/bbs/2023/7/16/Sdjksdj532XXX.png
56
            String filename = dir+"/"+datePath+"/"+newFileName;
57
            Map<String,Object> map = new HashMap<>();
58
            map.put("url",staticpath+"/uploadimg/"+filename);
59
            map.put("size",multipartFile.getSize());
60
            map.put("ext",imgSuffix);
61
            map.put("filename",oldFilename);
62
            map.put("rpath",datePath+"/"+newFileName);
63
            return map;
64
        } catch (IOException e) {
65
            e.printStackTrace();
66
            return null;
67
        }
68
    }
69
}

展开收起

对controller进行封装

1
package com.nacl.controller;
2

3
import com.nacl.server.UploadServe;
4
import org.springframework.beans.factory.annotation.Autowired;
5
import org.springframework.stereotype.Controller;
6
import org.springframework.web.bind.annotation.PostMapping;
7
import org.springframework.web.bind.annotation.RequestParam;
8
import org.springframework.web.bind.annotation.ResponseBody;
9
import org.springframework.web.multipart.MultipartFile;
10

11
import javax.servlet.http.HttpServletRequest;
12
import java.util.Map;
13

14
/**
15
 * @author HAOYANG
16
 * @create 2023-07-16 11:40
17
 */
18
@Controller
19
public class UploadController {
20

21
    @Autowired
22
    UploadServe uploadServe;
23
    /**
24
     * 文件上传具体实现
25
     *
26
     * @param multipartFile
27
     * @param request
28
     * @return
29
     */
30
    @PostMapping("/upload/file")
31
    @ResponseBody
32
    public Map<String, Object> upload(@RequestParam("file")MultipartFile multipartFile, HttpServletRequest request){
33
        if (multipartFile.isEmpty()){
34
            return null;
35
        }
36
        //原文件大小
37
        long size = multipartFile.getSize();
38
        //原文件名
39
        String originalFilename = multipartFile.getOriginalFilename();
40
        //原文件类型
41
        String contentType = multipartFile.getContentType();
42
        //1:获取用户指定的文件夹。问这个文件夹为什么要从页面上传递过来呢?
43
        //原因是:傲隔离，不司业务，不同文件放在不同的目录中
44
        String dir = request.getParameter("dir");
45
        return uploadServe.uploadImg(multipartFile,dir);
46
    }
47
}

展开收起

现在方式--->OSS对象存储#

1. 注册阿里云#

image-20230716144917055

2. 购买OSS对象存储#

image-20230716145045516

3.创建Bucket文件存储桶#

Bucket相当于本地存储的文件夹

1.创建Bucket列表

image-20230716145152910

2.创建好后找到SDK下载

image-20230716145222750

image-20230716145246316

4.安装SDK#

image-20230716145333398

导入依赖：#

5.导入oss的sdk依赖

定义OssUplaodService对接文件上传实现简单上传文件：

1
// Endpoint以华东1（杭州）为例，其它Region请按实际情况填写。
2
        String endpoint = "https://oss-cn-hangzhou.aliyuncs.com";
3
        // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
4
        String accessKeyId = "yourAccessKeyId";
5
        String accessKeySecret = "yourAccessKeySecret";
6
        // 填写Bucket名称，例如examplebucket。
7
        String bucketName = "examplebucket";
8
        // 填写Object完整路径，例如exampledir/exampleobject.txt。Object完整路径中不能包含Bucket名称。
9
        String objectName = "exampledir/exampleobject.txt";
10

11
        // 创建OSSClient实例。
12
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
13

14
        try {
15
            String content = "Hello OSS";
16
            ossClient.putObject(bucketName, objectName, new ByteArrayInputStream(content.getBytes()));
17
        } catch (OSSException oe) {
18
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
19
                    + "but was rejected with an error response for some reason.");
20
            System.out.println("Error Message:" + oe.getErrorMessage());
21
            System.out.println("Error Code:" + oe.getErrorCode());
22
            System.out.println("Request ID:" + oe.getRequestId());
23
            System.out.println("Host ID:" + oe.getHostId());
24
        } catch (ClientException ce) {
25
            System.out.println("Caught an ClientException, which means the client encountered "
26
                    + "a serious internal problem while trying to communicate with OSS, "
27
                    + "such as not being able to access the network.");
28
            System.out.println("Error Message:" + ce.getMessage());
29
        } finally {
30
            if (ossClient != null) {
31
                ossClient.shutdown();
32
            }
33
        }

展开收起

填写对应参数：

image-20230716145604882

image-20230716145618170

image-20230716145630779

image-20230716145650367

代码展示：#

本地文件上传测试

1
package com.tian.service;
2

3
import com.aliyun.oss.ClientException;
4
import com.aliyun.oss.OSS;
5
import com.aliyun.oss.OSSClientBuilder;
6
import com.aliyun.oss.OSSException;
7
import com.aliyun.oss.model.CannedAccessControlList;
8
import org.springframework.web.multipart.MultipartFile;
9

10
import java.io.ByteArrayInputStream;
11
import java.io.File;
12
import java.io.FileInputStream;
13
import java.io.InputStream;
14
import java.text.SimpleDateFormat;
15
import java.util.Date;
16
import java.util.UUID;
17

18
public class OSSservice {
19
    public static void main(String[] args) {
20
        String uploadfile = uploadfile(new File("e://1.txt"));
21
        System.out.println(uploadfile);
22

23
    }
24
    public static String uploadfile(File multipartFile){
25
        // Endpoint以华东1（杭州）为例，其它Region请按实际情况填写。
26
        String endpoint = "oss-cn-beijing.aliyuncs.com";
27
        // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
28
        String accessKeyId = "自己的accessKeyId";
29
        String accessKeySecret = "自己的accessKeySecret";
30
        // 填写Bucket名称，例如examplebucket。
31
        String bucketName = "atian-123";
32
        // 创建OSSClient实例。
33
        OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
34
        try {
35
            //如果桶不存在，创建桶。
36
            if(!ossClient.doesBucketExist(bucketName)){
37
                //创建桶
38
                ossClient.createBucket(bucketName);
39
                //设置oss实例的访问权限：公共读
40
                ossClient.setBucketAcl(bucketName, CannedAccessControlList.PublicRead);
41
            }
42
            //2.获取文件上传的流
43
            InputStream inputStream = new FileInputStream(multipartFile);
44
            //3.构建日期目录
45
            SimpleDateFormat dateFormat = new SimpleDateFormat(  "yyyy/MM/dd");
46
            String datePath = dateFormat.format(new Date());
47
            //4.获取文件名
48
            String originalFilename = multipartFile.getName();
49
            String filename = UUID.randomUUID().toString();//生成文件名
50
            String substring = originalFilename.substring(originalFilename.lastIndexOf("."));//截取出后缀名
51
            String newName = filename + substring;//拼接
52
            String fileUrl = datePath+"/"+newName;//完整的目录
53
            //5.文件上传到阿里云服务器
54
            ossClient.putObject(bucketName,fileUrl,inputStream);
55
            //6.返回文件的访问路径
56
            return "https://"+bucketName+"."+endpoint +"/"+fileUrl;
57
            //https://atian-123.oss-cn-beijing.aliyuncs.com/2022/08/11/dfab1c62-8b2f-42e8-baa2-8ca18333a681.txt
58
            //成功返回
59
        } catch (OSSException oe) {
60
            System.out.println("Caught an OSSException, which means your request made it to OSS, "
61
                    + "but was rejected with an error response for some reason.");
62
            System.out.println("Error Message:" + oe.getErrorMessage());
63
            System.out.println("Error Code:" + oe.getErrorCode());
64
            System.out.println("Request ID:" + oe.getRequestId());
65
            System.out.println("Host ID:" + oe.getHostId());
66
            return "fail";
67
        } catch (ClientException ce) {
68
            System.out.println("Caught an ClientException, which means the client encountered "
69
                    + "a serious internal problem while trying to communicate with OSS, "
70
                    + "such as not being able to access the network.");
71
            System.out.println("Error Message:" + ce.getMessage());
72
            return "fail";
73
        } catch (Exception e) {
74
            System.out.println("获取文件流对象失败！！");
75
            return "fail";
76
        }finally {
77
            if (ossClient != null) {
78
                ossClient.shutdown();
79
            }
80
        }
81
    }
82
}

展开收起

正常代码：

1
    //-------------------------------------------------------------------------------------------------------------------
2
package com.tian.service;
3

4
import com.aliyun.oss.ClientException;
5
import com.aliyun.oss.OSS;
6
import com.aliyun.oss.OSSClientBuilder;
7
import com.aliyun.oss.OSSException;
8
import com.aliyun.oss.model.CannedAccessControlList;
9
import org.springframework.web.multipart.MultipartFile;
10

11
import java.io.ByteArrayInputStream;
12
import java.io.File;
13
import java.io.FileInputStream;
14
import java.io.InputStream;
15
import java.text.SimpleDateFormat;
16
import java.util.Date;
17
import java.util.UUID;
18

19
public class OSSservice {
20
    public String uploadfile(MultipartFile multipartFile){
21
    // Endpoint以华东1（杭州）为例，其它Region请按实际情况填写。
22
    String endpoint = "oss-cn-beijing.aliyuncs.com";
23
    // 阿里云账号AccessKey拥有所有API的访问权限，风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维，请登录RAM控制台创建RAM用户。
24
    String accessKeyId = "自己的accessKeyId";
25
    String accessKeySecret = "zGzSWHp4GWUT048gt6MQQMbnUV2dvA";
26
    // 填写Bucket名称，例如examplebucket。
27
    String bucketName = "atian-123";
28
    // 创建OSSClient实例。
29
    OSS ossClient = new OSSClientBuilder().build(endpoint, accessKeyId, accessKeySecret);
30
        try {
31
            //如果桶不存在，创建桶。
32
            if(!ossClient.doesBucketExist(bucketName)){
33
                //创建桶
34
                ossClient.createBucket(bucketName);
35
                //设置oss实例的访问权限：公共读
36
                ossClient.setBucketAcl(bucketName, CannedAccessControlList.PublicRead);
37
            }
38
            //2.获取文件上传的流
39
            InputStream inputStream = multipartFile.getInputStream();
40
            //3.构建日期目录
41
            SimpleDateFormat dateFormat = new SimpleDateFormat(  "yyyy/MM/dd");
42
            String datePath = dateFormat.format(new Date());
43
            //4.获取文件名
44
            String originalFilename = multipartFile.getOriginalFilename();
45
            String filename = UUID.randomUUID().toString();//生成文件名
46
            String substring = originalFilename.substring(originalFilename.lastIndexOf("."));//截取出后缀名
47
            String newName = filename + substring;//拼接
48
            String fileUrl = datePath+"/"+newName;//完整的目录
49
            //5.文件上传到阿里云服务器
50
            ossClient.putObject(bucketName,fileUrl,inputStream);
51
            //6.返回文件的访问路径
52
            return "https://"+bucketName+"."+endpoint +"/"+fileUrl;
53
    } catch (OSSException oe) {
54
        System.out.println("Caught an OSSException, which means your request made it to OSS, "
55
                + "but was rejected with an error response for some reason.");
56
        System.out.println("Error Message:" + oe.getErrorMessage());
57
        System.out.println("Error Code:" + oe.getErrorCode());
58
        System.out.println("Request ID:" + oe.getRequestId());
59
        System.out.println("Host ID:" + oe.getHostId());
60
            return "fail";
61
    } catch (ClientException ce) {
62
        System.out.println("Caught an ClientException, which means the client encountered "
63
                + "a serious internal problem while trying to communicate with OSS, "
64
                + "such as not being able to access the network.");
65
        System.out.println("Error Message:" + ce.getMessage());
66
            return "fail";
67
    } catch (Exception e) {
68
            System.out.println("获取文件流对象失败！！");
69
            return "fail";
70
        }finally {
71
            if (ossClient != null) {
72
                ossClient.shutdown();
73
            }
74
        }
75
    }
76
}

展开收起

image-20230716145758726

SpringBoot整合FFmpeg进行视频分片上传

Fri, 19 Dec 2025 00:00:00 GMT

SpringBoot整合FFmpeg进行视频分片上传------>Windows#

分片上传的核心思路：#

将文件按一定的分割规则（静态或动态设定，如手动设置20M为一个分片），用slice分割成多个数据块。
为每个文件生成一个唯一标识Key，用于多数据块上传时区分所属文件。
所有分片上传完成，服务端校验合并标识为Key的所有分片为一个最终文件。

分片上传的意义：#

将文件分片上传，在网络环境不佳时，可以对文件上传失败的部分重新上传，避免了每次上传都需要从文件起始位置上传的问题。分片的附带好处还能很方便的实现进度条。

分片上传的原理：#

使用ffmpeg，把视频文件切片成m3u8，并且通过springboot，可以实现在线的点播。客户端上传视频到服务器，服务器对视频进行切片后，返回m3u8，封面等访问路径。可以在线的播放。

准备工作：#

需要先在本机安装FFmpeg，并且添加到PATH环境变量

一：下载、解压#

下载地址：http://ffmpeg.org/download.html

下载解压至本地文件夹下（以下是我的安装路径）

image-20230729114220629

二：配置环境变量：#

先进入bin目录获取路径：D:\study\ffmpeg-6.0-full_build\bin

配置环境变量path

image-20230729114825491

三：使用命令行窗口检验是否安装成功#

Windows+R 输入 cmd 进入命令窗口

输入“ffmpeg –version” 如果出现如下说明配置成功

image-20230729114946644

代码展示：#

pom文件#

pom.xml

1
<?xml version="1.0" encoding="UTF-8"?>
2
<project xmlns="http://maven.apache.org/POM/4.0.0"
3
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
4
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
5
    <modelVersion>4.0.0</modelVersion>
6

7
    <groupId>com.nacl</groupId>
8
    <artifactId>cs</artifactId>
9
    <version>1.0-SNAPSHOT</version>
10
<parent>
11
    <groupId>org.springframework.boot</groupId>
12
    <artifactId>spring-boot-starter-parent</artifactId>
13
    <version>2.7.2</version>
14
</parent>
15
    <properties>
16
        <maven.compiler.source>11</maven.compiler.source>
17
        <maven.compiler.target>11</maven.compiler.target>
18
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
19
        <javacv.version>1.5.4</javacv.version>
20
        <ffmpeg.version>4.3.1-1.5.4</ffmpeg.version>
21
    </properties>
22
    <dependencies>
23

24
        <dependency>
25
            <groupId>commons-lang</groupId>
26
            <artifactId>commons-lang</artifactId>
27
            <version>2.6</version>
28
        </dependency>
29

30
        <dependency>
31
            <groupId>commons-fileupload</groupId>
32
            <artifactId>commons-fileupload</artifactId>
33
            <version>1.2.2</version>
34
        </dependency>
35
        <dependency>
36
            <groupId>commons-io</groupId>
37
            <artifactId>commons-io</artifactId>
38
            <version>2.5</version>
39
        </dependency>
40

41
        <!--web 模块 -->
42
        <dependency>
43
            <groupId>org.springframework.boot</groupId>
44
            <artifactId>spring-boot-starter-web</artifactId>
45
            <exclusions>
46
                <!--排除tomcat依赖 -->
47
                <exclusion>
48
                    <artifactId>spring-boot-starter-tomcat</artifactId>
49
                    <groupId>org.springframework.boot</groupId>
50
                </exclusion>
51
            </exclusions>
52
        </dependency>
53

54
        <!--undertow容器 -->
55
        <dependency>
56
            <groupId>org.springframework.boot</groupId>
57
            <artifactId>spring-boot-starter-undertow</artifactId>
58
        </dependency>
59

60
        <dependency>
61
            <groupId>org.springframework.boot</groupId>
62
            <artifactId>spring-boot-starter-test</artifactId>
63
            <scope>test</scope>
64
        </dependency>
65

66
        <!--      javacv 和 ffmpeg的依赖包      -->
67
        <dependency>
68
            <groupId>org.bytedeco</groupId>
69
            <artifactId>javacv</artifactId>
70
            <version>${javacv.version}</version>
71
            <exclusions>
72
                <exclusion>
73
                    <groupId>org.bytedeco</groupId>
74
                    <artifactId>*</artifactId>
75
                </exclusion>
76
            </exclusions>
77
        </dependency>
78

79
        <dependency>
80
            <groupId>org.bytedeco</groupId>
81
            <artifactId>ffmpeg-platform</artifactId>
82
            <version>${ffmpeg.version}</version>
83
        </dependency>
84

85
        <dependency>
86
            <groupId>cn.hutool</groupId>
87
            <artifactId>hutool-all</artifactId>
88
            <version>5.6.5</version>
89
        </dependency>
90

91
        <dependency>
92
            <groupId>log4j</groupId>
93
            <artifactId>log4j</artifactId>
94
            <version>1.2.17</version>
95
        </dependency>
96

97
        <dependency>
98
            <groupId>org.springframework.boot</groupId>
99
            <artifactId>spring-boot-starter-test</artifactId>
100
            <scope>test</scope>
101
        </dependency>
102

103
        <dependency>
104
            <groupId>org.junit.vintage</groupId>
105
            <artifactId>junit-vintage-engine</artifactId>
106
            <scope>test</scope>
107
        </dependency>
108

109
        <dependency>
110
            <groupId>org.springframework.boot</groupId>
111
            <artifactId>spring-boot-starter-web</artifactId>
112
            <exclusions>
113
                <exclusion>
114
                    <groupId>org.springframework.boot</groupId>
115
                    <artifactId>spring-boot-starter-tomcat</artifactId>
116
                </exclusion>
117
            </exclusions>
118
        </dependency>
119

120
        <dependency>
121
            <groupId>org.springframework.boot</groupId>
122
            <artifactId>spring-boot-starter-undertow</artifactId>
123
        </dependency>
124

125
        <dependency>
126
            <groupId>commons-codec</groupId>
127
            <artifactId>commons-codec</artifactId>
128
        </dependency>
129

130
        <dependency>
131
            <groupId>com.google.code.gson</groupId>
132
            <artifactId>gson</artifactId>
133
        </dependency>
134
        <dependency>
135
            <groupId>org.projectlombok</groupId>
136
            <artifactId>lombok</artifactId>
137
        </dependency>
138
    </dependencies>
139
    <build>
140
        <finalName>${project.artifactId}</finalName>
141
        <plugins>
142
            <plugin>
143
                <groupId>org.springframework.boot</groupId>
144
                <artifactId>spring-boot-maven-plugin</artifactId>
145
                <configuration>
146
                    <executable>true</executable>
147
                </configuration>
148
            </plugin>
149
        </plugins>
150
    </build>
151
</project>

展开收起

yml配置#

application.yml

1
server:
2
  port: 8086
3

4
app:
5
  # 存储转码视频的文件夹
6
  video-folder: D:\ffmpegVedio\
7

8
spring:
9
  servlet:
10
    multipart:
11
      enabled: true
12
      # 不限制文件大小
13
      max-file-size: -1
14
      # 不限制请求体大小
15
      max-request-size: -1
16
      # 临时IO目录
17
      location: "${java.io.tmpdir}"
18
      # 不延迟解析
19
      resolve-lazily: false
20
      # 超过1Mb，就IO到临时目录
21
      file-size-threshold: 1MB
22
  web:
23
    resources:
24
      static-locations:
25
        - "classpath:/static/"
26
        - "file:${app.video-folder}" # 把视频文件夹目录，添加到静态资源目录列表

展开收起

工具类#

MediaInfo

1
package com.nacl.util;
2

3
import java.util.List;
4

5
import com.google.gson.annotations.SerializedName;
6
/**
7
 * @author HAOYANG
8
 * @create 2023-07-29 10:31
9
 */
10
public class MediaInfo {
11
    public static class Format {
12
        @SerializedName("bit_rate")
13
        private String bitRate;
14
        public String getBitRate() {
15
            return bitRate;
16
        }
17
        public void setBitRate(String bitRate) {
18
            this.bitRate = bitRate;
19
        }
20
    }
21

22
    public static class Stream {
23
        @SerializedName("index")
24
        private int index;
25

26
        @SerializedName("codec_name")
27
        private String codecName;
28

29
        @SerializedName("codec_long_name")
30
        private String codecLongame;
31

32
        @SerializedName("profile")
33
        private String profile;
34
    }
35

36
    @SerializedName("streams")
37
    private List<Stream> streams;
38

39
    @SerializedName("format")
40
    private Format format;
41

42
    public List<Stream> getStreams() {
43
        return streams;
44
    }
45

46
    public void setStreams(List<Stream> streams) {
47
        this.streams = streams;
48
    }
49

50
    public Format getFormat() {
51
        return format;
52
    }
53

54
    public void setFormat(Format format) {
55
        this.format = format;
56
    }
57
}

展开收起

TranscodeConfig

1
package com.nacl.util;
2

3
import lombok.Data;
4
/**
5
 * @author HAOYANG
6
 * @create 2023-07-29 10:32
7
 */
8
@Data
9
public class TranscodeConfig {
10

11
    private String poster = "00:00:00.001";        // 截取封面的时间      HH:mm:ss.[SSS]
12
    private String tsSeconds = "15";      // ts分片大小，单位是秒
13
    private String cutStart;      // 视频裁剪，开始时间    HH:mm:ss.[SSS]
14
    private String cutEnd;        // 视频裁剪，结束时间    HH:mm:ss.[SSS]
15
    public String getPoster() {
16
        return poster;
17
    }
18

19
    public void setPoster(String poster) {
20
        this.poster = poster;
21
    }
22

23
    public String getTsSeconds() {
24
        return tsSeconds;
25
    }
26

27
    public void setTsSeconds(String tsSeconds) {
28
        this.tsSeconds = tsSeconds;
29
    }
30

31
    public String getCutStart() {
32
        return cutStart;
33
    }
34

35
    public void setCutStart(String cutStart) {
36
        this.cutStart = cutStart;
37
    }
38

39
    public String getCutEnd() {
40
        return cutEnd;
41
    }
42

43
    public void setCutEnd(String cutEnd) {
44
        this.cutEnd = cutEnd;
45
    }
46

47
    @Override
48
    public String toString() {
49
        return "TranscodeConfig [poster=" + poster + ", tsSeconds=" + tsSeconds + ", cutStart=" + cutStart + ", cutEnd="
50
                + cutEnd + "]";
51
    }
52
}

展开收起

FFmpegUtils

1
package com.nacl.util;
2

3
import java.io.BufferedReader;
4
import java.io.File;
5
import java.io.IOException;
6
import java.io.InputStreamReader;
7
import java.nio.charset.StandardCharsets;
8
import java.nio.file.Files;
9
import java.nio.file.Path;
10
import java.nio.file.Paths;
11
import java.nio.file.StandardOpenOption;
12
import java.security.NoSuchAlgorithmException;
13
import java.time.LocalDate;
14
import java.time.format.DateTimeFormatter;
15
import java.util.*;
16

17
import javax.crypto.KeyGenerator;
18

19
import org.apache.commons.codec.binary.Hex;
20
import org.slf4j.Logger;
21
import org.slf4j.LoggerFactory;
22
import org.springframework.http.HttpStatus;
23
import org.springframework.http.ResponseEntity;
24
import org.springframework.util.StringUtils;
25

26
import com.google.gson.Gson;
27
import org.springframework.web.bind.annotation.RequestPart;
28
import org.springframework.web.multipart.MultipartFile;
29
/**
30
 * @author HAOYANG
31
 * @create 2023-07-29 10:33
32
 */
33

34
public class FFmpegUtils {
35

36
    private static final Logger LOGGER = LoggerFactory.getLogger(FFmpegUtils.class);
37

38
    // 跨平台换行符
39
    private static final String LINE_SEPARATOR = System.getProperty("line.separator");
40

41
    /**
42
     * 生成随机16个字节的AESKEY
43
     * @return
44
     */
45
    private static byte[] genAesKey ()  {
46
        try {
47
            KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
48
            keyGenerator.init(128);
49
            return keyGenerator.generateKey().getEncoded();
50
        } catch (NoSuchAlgorithmException e) {
51
            return null;
52
        }
53
    }
54

55
    /**
56
     * 在指定的目录下生成key_info, key文件，返回key_info文件
57
     * @param folder
58
     * @throws IOException
59
     */
60
    private static Path genKeyInfo(String folder) throws IOException {
61
        // AES 密钥
62
        byte[] aesKey = genAesKey();
63
        // AES 向量
64
        String iv = Hex.encodeHexString(genAesKey());
65

66
        // key 文件写入
67
        Path keyFile = Paths.get(folder, "key");
68
        Files.write(keyFile, aesKey, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
69

70
        // key_info 文件写入
71
        StringBuilder stringBuilder = new StringBuilder();
72
        stringBuilder.append("key").append(LINE_SEPARATOR);          // m3u8加载key文件网络路径
73
        stringBuilder.append(keyFile.toString()).append(LINE_SEPARATOR);  // FFmeg加载key_info文件路径
74
        stringBuilder.append(iv);                      // ASE 向量
75

76
        Path keyInfo = Paths.get(folder, "key_info");
77

78
        Files.write(keyInfo, stringBuilder.toString().getBytes(), StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
79

80
        return keyInfo;
81
    }
82

83
    /**
84
     * 指定的目录下生成 master index.m3u8 文件
85
     * @param file      master m3u8文件地址
86
     * @param indexPath      访问子index.m3u8的路径
87
     * @param bandWidth      流码率
88
     * @throws IOException
89
     */
90
    private static void genIndex(String file, String indexPath, String bandWidth) throws IOException {
91
        StringBuilder stringBuilder = new StringBuilder();
92
        stringBuilder.append("#EXTM3U").append(LINE_SEPARATOR);
93
        stringBuilder.append("#EXT-X-STREAM-INF:BANDWIDTH=" + bandWidth).append(LINE_SEPARATOR);  // 码率
94
        stringBuilder.append(indexPath);
95
        Files.write(Paths.get(file), stringBuilder.toString().getBytes(StandardCharsets.UTF_8), StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
96
    }
97

98
    /**
99
     * 转码视频为m3u8
100
     * @param source        源视频
101
     * @param destFolder      目标文件夹
102
     * @param config        配置信息
103
     * @throws IOException
104
     * @throws InterruptedException
105
     */
106
    public static void transcodeToM3u8(String source, String destFolder, TranscodeConfig config) throws IOException, InterruptedException {
107

108
        // 判断源视频是否存在
109
        if (!Files.exists(Paths.get(source))) {
110
            throw new IllegalArgumentException("文件不存在：" + source);
111
        }
112

113
        // 创建工作目录
114
        Path workDir = Paths.get(destFolder, "ts");
115
        Files.createDirectories(workDir);
116

117
        // 在工作目录生成KeyInfo文件
118
        Path keyInfo = genKeyInfo(workDir.toString());
119

120
        // 构建命令
121
        List<String> commands = new ArrayList<>();
122
        commands.add("ffmpeg");
123
        commands.add("-i")            ;commands.add(source);          // 源文件
124
        commands.add("-c:v")          ;commands.add("libx264");        // 视频编码为H264
125
        commands.add("-c:a")          ;commands.add("copy");          // 音频直接copy
126
        commands.add("-hls_key_info_file")    ;commands.add(keyInfo.toString());    // 指定密钥文件路径
127
        commands.add("-hls_time")        ;commands.add(config.getTsSeconds());  // ts切片大小
128
        commands.add("-hls_playlist_type")    ;commands.add("vod");          // 点播模式
129
        commands.add("-hls_segment_filename")  ;commands.add("%06d.ts");        // ts切片文件名称
130

131
        if (StringUtils.hasText(config.getCutStart())) {
132
            commands.add("-ss")          ;commands.add(config.getCutStart());  // 开始时间
133
        }
134
        if (StringUtils.hasText(config.getCutEnd())) {
135
            commands.add("-to")          ;commands.add(config.getCutEnd());    // 结束时间
136
        }
137
        commands.add("index.m3u8");                            // 生成m3u8文件
138

139
        // 构建进程
140
        Process process = new ProcessBuilder()
141
                .command(commands)
142
                .directory(workDir.toFile())
143
                .start()
144
                ;
145

146
        // 读取进程标准输出
147
        new Thread(() -> {
148
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
149
                String line = null;
150
                while ((line = bufferedReader.readLine()) != null) {
151
                    LOGGER.info(line);
152
                }
153
            } catch (IOException e) {
154
            }
155
        }).start();
156

157
        // 读取进程异常输出
158
        new Thread(() -> {
159
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getErrorStream()))) {
160
                String line = null;
161
                while ((line = bufferedReader.readLine()) != null) {
162
                    LOGGER.info(line);
163
                }
164
            } catch (IOException e) {
165
            }
166
        }).start();
167

168

169
        // 阻塞直到任务结束
170
        if (process.waitFor() != 0) {
171
            throw new RuntimeException("视频切片异常");
172
        }
173

174
        // 切出封面
175
        if (!screenShots(source, String.join(File.separator, destFolder, "poster.jpg"), config.getPoster())) {
176
            throw new RuntimeException("封面截取异常");
177
        }
178

179
        // 获取视频信息
180
        final MediaInfo[] mediaInfo = {getMediaInfo(source)};
181
        if (mediaInfo[0] == null) {
182
            throw new RuntimeException("获取媒体信息异常");
183
        }
184

185
        // 生成index.m3u8文件
186
        genIndex(String.join(File.separator, destFolder, "index.m3u8"), "ts/index.m3u8", mediaInfo[0].getFormat().getBitRate());
187

188
        // 删除keyInfo文件
189
        Files.delete(keyInfo);
190
    }
191

192
    /**
193
     * 获取视频文件的媒体信息
194
     * @param source
195
     * @return
196
     * @throws IOException
197
     * @throws InterruptedException
198
     */
199
    public static MediaInfo getMediaInfo(String source) throws IOException, InterruptedException {
200
        List<String> commands = new ArrayList<>();
201
        commands.add("ffprobe");
202
        commands.add("-i")        ;commands.add(source);
203
        commands.add("-show_format");
204
        commands.add("-show_streams");
205
        commands.add("-print_format")  ;commands.add("json");
206

207
        Process process = new ProcessBuilder(commands)
208
                .start();
209

210
        MediaInfo mediaInfo = null;
211

212
        try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
213
            mediaInfo = new Gson().fromJson(bufferedReader, MediaInfo.class);
214
        } catch (IOException e) {
215
            e.printStackTrace();
216
        }
217

218
        if (process.waitFor() != 0) {
219
            return null;
220
        }
221

222
        return mediaInfo;
223
    }
224

225
    /**
226
     * 截取视频的指定时间帧，生成图片文件
227
     * @param source    源文件
228
     * @param file      图片文件
229
     * @param time      截图时间 HH:mm:ss.[SSS]
230
     * @throws IOException
231
     * @throws InterruptedException
232
     */
233
    public static boolean screenShots(String source, String file, String time) throws IOException, InterruptedException {
234

235
        List<String> commands = new ArrayList<>();
236
        commands.add("ffmpeg");
237
        commands.add("-i")        ;commands.add(source);
238
        commands.add("-ss")        ;commands.add(time);
239
        commands.add("-y");
240
        commands.add("-q:v")      ;commands.add("1");
241
        commands.add("-frames:v")    ;commands.add("1");
242
        commands.add("-f");        ;commands.add("image2");
243
        commands.add(file);
244

245
        Process process = new ProcessBuilder(commands)
246
                .start();
247

248
        // 读取进程标准输出
249
        new Thread(() -> {
250
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
251
                String line = null;
252
                while ((line = bufferedReader.readLine()) != null) {
253
                    LOGGER.info(line);
254
                }
255
            } catch (IOException e) {
256
            }
257
        }).start();
258

259
        // 读取进程异常输出
260
        new Thread(() -> {
261
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getErrorStream()))) {
262
                String line = null;
263
                while ((line = bufferedReader.readLine()) != null) {
264
                    LOGGER.error(line);
265
                }
266
            } catch (IOException e) {
267
            }
268
        }).start();
269

270
        return process.waitFor() == 0;
271
    }
272
}

展开收起

controller调用#

UploadController

1
package com.nacl.controller;
2

3
/**
4
 * @author HAOYANG
5
 * @create 2023-07-29 10:33
6
 */
7
import java.io.IOException;
8
import java.nio.file.Files;
9
import java.nio.file.Path;
10
import java.nio.file.Paths;
11
import java.time.LocalDate;
12
import java.time.format.DateTimeFormatter;
13
import java.util.HashMap;
14
import java.util.Map;
15
import java.util.UUID;
16

17
import lombok.extern.slf4j.Slf4j;
18
import org.slf4j.Logger;
19
import org.slf4j.LoggerFactory;
20
import org.springframework.beans.factory.annotation.Value;
21
import org.springframework.http.HttpStatus;
22
import org.springframework.http.ResponseEntity;
23
import org.springframework.web.bind.annotation.*;
24
import org.springframework.web.multipart.MultipartFile;
25
import com.nacl.util.TranscodeConfig;
26
import  com.nacl.util.FFmpegUtils;
27

28
import static com.nacl.util.FFmpegUtils.transcodeToM3u8;
29

30
@Slf4j
31
@RestController
32
@RequestMapping("/uploadController")
33
public class UploadController {
34

35
    @Value("${app.video-folder}")
36
    private String videoFolder;
37

38
    private Path tempDir = Paths.get(System.getProperty("java.io.tmpdir"));
39

40
    /**
41
     * 上传视频进行切片处理，返回访问路径
42
     * @param video
43
     * @param transcodeConfig
44
     * @return
45
     * @throws IOException
46
     */
47
    @PostMapping("/upload")
48
    @CrossOrigin
49
    public Object upload (@RequestPart(name = "file", required = true) MultipartFile video,
50
                          @RequestPart(name = "config", required = true) TranscodeConfig transcodeConfig) throws IOException {
51
        log.info("文件信息：title={}, size={}", video.getOriginalFilename(), video.getSize());
52
        log.info("转码配置：{}", transcodeConfig);
53

54
        // 原始文件名称，也就是视频的标题
55
        String title = video.getOriginalFilename();
56

57
        // io到临时文件
58
        Path tempFile = tempDir.resolve(title);
59
        log.info("io到临时文件：{}", tempFile.toString());
60

61
        try {
62
            video.transferTo(tempFile);
63

64
            // 删除后缀
65
            title = title.substring(0, title.lastIndexOf(".")) + "-" + UUID.randomUUID().toString().replaceAll("-", "");
66

67
            // 按照日期生成子目录
68
            String today = DateTimeFormatter.ofPattern("yyyyMMdd").format(LocalDate.now());
69

70
            // 尝试创建视频目录
71
            Path targetFolder = Files.createDirectories(Paths.get(videoFolder, today, title));
72

73
            log.info("创建文件夹目录：{}", targetFolder);
74
            Files.createDirectories(targetFolder);
75

76
            // 执行转码操作
77
            log.info("开始转码");
78
            try {
79
                transcodeToM3u8(tempFile.toString(), targetFolder.toString(), transcodeConfig);
80
            } catch (Exception e) {
81
                log.error("转码异常：{}", e.getMessage());
82
                Map<String, Object> result = new HashMap<>();
83
                result.put("success", false);
84
                result.put("message", e.getMessage());
85
                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(result);
86
            }
87

88
            // 封装结果
89
            Map<String, Object> videoInfo = new HashMap<>();
90
            videoInfo.put("title", title);
91
            videoInfo.put("m3u8", String.join("/", "", today, title, "index.m3u8"));
92
            videoInfo.put("poster", String.join("/", "", today, title, "poster.jpg"));
93

94
            //返回数据
95
            Map<String, Object> result = new HashMap<>();
96
            result.put("success", true);
97
            result.put("data", videoInfo);
98
            return result;
99
        } finally {
100
            // 始终删除临时文件
101
            Files.delete(tempFile);
102
        }
103
    }
104
}

展开收起

Url转换MultipartFile的工具类#

如controller中参数传的是URL 使用以下工具类转换一下即可#

UrlToMultipartFile

1
package com.nacl.util;
2

3
import org.apache.commons.fileupload.FileItem;
4
import org.apache.commons.fileupload.FileItemFactory;
5
import org.apache.commons.fileupload.disk.DiskFileItemFactory;
6
import org.apache.commons.lang.RandomStringUtils;
7
import org.slf4j.Logger;
8
import org.slf4j.LoggerFactory;
9
import org.springframework.web.multipart.MultipartFile;
10
import org.springframework.web.multipart.commons.CommonsMultipartFile;
11

12
import java.io.*;
13
import java.net.HttpURLConnection;
14
import java.net.URL;
15

16
/**
17
 * @author HAOYANG
18
 * @create 2023-07-29 10:36
19
 */
20
public class UrlToMultipartFile {
21

22
    private static final Logger LOGGER = LoggerFactory.getLogger(UrlToMultipartFile.class);
23

24
    /**
25
     * inputStream 转 File
26
     */
27
    public static File inputStreamToFile(InputStream ins, String name) throws Exception{
28
        //System.getProperty("java.io.tmpdir")临时目录+File.separator目录中间的间隔符+文件名
29
        File file = new File(System.getProperty("java.io.tmpdir") + File.separator + name);
30
        OutputStream os = new FileOutputStream(file);
31
        int bytesRead;
32
        int len = 8192;
33
        byte[] buffer = new byte[len];
34
        while ((bytesRead = ins.read(buffer, 0, len)) != -1) {
35
            os.write(buffer, 0, bytesRead);
36
        }
37
        os.close();
38
        ins.close();
39
        return file;
40
    }
41

42
    /**
43
     * file转multipartFile
44
     */
45
    public static MultipartFile fileToMultipartFile(File file) {
46
        FileItemFactory factory = new DiskFileItemFactory(16, null);
47
        FileItem item=factory.createItem(file.getName(),"text/plain",true,file.getName());
48
        int bytesRead = 0;
49
        byte[] buffer = new byte[8192];
50
        try {
51
            FileInputStream fis = new FileInputStream(file);
52
            OutputStream os = item.getOutputStream();
53
            while ((bytesRead = fis.read(buffer, 0, 8192)) != -1) {
54
                os.write(buffer, 0, bytesRead);
55
            }
56
            os.close();
57
            fis.close();
58
        } catch (IOException e) {
59
            e.printStackTrace();
60
        }
61
        return new CommonsMultipartFile(item);
62
    }
63

64
    //url转MultipartFile
65
    public static MultipartFile urlToMultipartFile(String url) throws Exception {
66
        File file = null;
67
        MultipartFile multipartFile = null;
68
        try {
69
            HttpURLConnection httpUrl = (HttpURLConnection) new URL(url).openConnection();
70
            httpUrl.connect();
71
            file = UrlToMultipartFile.inputStreamToFile(httpUrl.getInputStream(),RandomStringUtils.randomAlphanumeric(8)+".mp4");
72
            LOGGER.info("---------"+file+"-------------");
73

74
            multipartFile = UrlToMultipartFile.fileToMultipartFile(file);
75
            httpUrl.disconnect();
76
        } catch (Exception e) {
77
            e.printStackTrace();
78
        }
79
        return multipartFile;
80
    }
81

82
}

展开收起

HTML文件进行测试#

请求路径：http://localhost:8086/cs.html #

cs.html

1
<!DOCTYPE html>
2
<html lang="en">
3
<head>
4
    <meta charset="UTF-8">
5
    <title>Title</title>
6
    <script src="https://cdn.jsdelivr.net/hls.js/latest/hls.min.js"></script>
7
</head>
8
<body>
9
选择转码文件： <input name="file" type="file" accept="video/*" onchange="upload(event)">
10
<hr/>
11
<video id="video"  width="500" height="400" controls="controls"></video>
12
</body>
13
<script>
14

15
    const video = document.getElementById('video');
16

17
    function upload (e){
18
        let files = e.target.files
19
        if (!files) {
20
            return
21
        }
22

23
        // TODO 转码配置这里固定死了
24
        var transCodeConfig = {
25
            poster: "00:00:00.001", // 截取第1毫秒作为封面
26
            tsSeconds: 15,
27
            cutStart: "",
28
            cutEnd: ""
29
        }
30

31
        // 执行上传
32
        let formData = new FormData();
33
        formData.append("file", files[0])
34
        formData.append("config", new Blob([JSON.stringify(transCodeConfig)], {type: "application/json; charset=utf-8"}))
35

36
        fetch('/uploadController/upload', {
37
            method: 'POST',
38
            body: formData
39
        })
40
            .then(resp =>  resp.json())
41
            .then(message => {
42
                if (message.success){
43
                    // 设置封面
44
                    video.poster = message.data.poster;
45

46
                    // 渲染到播放器
47
                    var hls = new Hls();
48
                    hls.loadSource(message.data.m3u8);
49
                    hls.attachMedia(video);
50
                } else {
51
                    alert("转码异常，详情查看控制台");
52
                    console.log(message.message);
53
                }
54
            })
55
            .catch(err => {
56
                alert("转码异常，详情查看控制台。。。");
57
                throw err
58
            })
59
    }
60
</script>
61
</html>

展开收起

SpringBoot整合FFmpeg进行视频分片上传------>Linux#

分片上传的核心思路：#

将文件按一定的分割规则（静态或动态设定，如手动设置20M为一个分片），用slice分割成多个数据块。
为每个文件生成一个唯一标识Key，用于多数据块上传时区分所属文件。
所有分片上传完成，服务端校验合并标识为Key的所有分片为一个最终文件。

分片上传的意义：#

分片上传的原理：#

准备工作：#

需要先在linux下安装FFmpeg，并配置环境变量

一：下载、解压#

使用命令下载：

Terminal window

1
wget https://johnvansickle.com/ffmpeg/release-source/ffmpeg-4.1.tar.xz
2
#使用命令解压：
3
cd  /root/FFmpeg
4
tar -xvJf ffmpeg-4.1.tar.xz
5
# 编辑准备
6
cd /root/FFmpeg/ffmpeg-4.1    # 切换到ffmpeg-4.1目录
7
yum install gcc  # 安装gcc编译器

yasm安装包

Terminal window

1
cd /root/FFmpeg
2
wget http://www.tortall.net/projects/yasm/releases/yasm-1.3.0.tar.gz  #下载源码包
3
tar zxvf yasm-1.3.0.tar.gz #解压
4
cd yasm-1.3.0 #进入目录
5
./configure #配置
6
make && make install #编译安装

安装FFmpeg

Terminal window

1
cd /root/FFmpeg/ffmpeg-4.1/
2
./configure --enable-shared --prefix=/usr/local/ffmpeg-4.1
3
make && make install #编译安装

下载x264

Terminal window

1
cd /root/libx264/
2
yum -y install git
3
git clone https://git.videolan.org/git/x264.git

安装nasm

Terminal window

1
tar -xvf nasm-2.14.02.tar.gz
2
cd nasm-2.14.02
3
./configure
4
make
5
sudo make install
6
#查看是否安装成功
7
nasm -version

安装x264

Terminal window

1
cd /root/FFmpeg/libx264/x264
2
./configure --prefix=/usr/softinstall/x264/ --includedir=/usr/local/include --libdir=/usr/local/lib --enable-shared
3
make
4
sudo make install

安装FFmpeg

Terminal window展开收起

1
#配置 /etc/ld.so.conf
2
vim /etc/ld.so.conf #通过vim指令进入位于etc目录中的ld.so.conf
3
#输入i进入插入模式，将第二行的内容插入到该文件
4
include ld.so.conf.d/*.conf
5
/usr/local/ffmpeg-4.1/lib
6

7
ldconfig  #ldconfig 是一个动态链接库管理命令，其目的为了让动态链接库为系统所共享。
8
make
9
sudo make install
10
# ffmpeg  -i  /root/FFmpeg/wukel.mp4  -c:v  libx264  -c:a  copy  -hls_key_info_file  /root/FFmpeg/video_folder/20220308/test1/  -hls_time  15  -hls_playlist_type  vod  -hls_segment_filename  %06d.ts  index.m3u8
11
ldd ffmpeg
12
cd /root/FFmpeg/ffmpeg-4.1
13
./configure --prefix=/usr/softinstall/ffmpeg --enable-gpl --enable-shared --enable-libx264
14

15
# 配置环境变量
16
vim /etc/profile
17
#配置如下
18
export FFMPEG_HOME=/usr/local/ffmpeg-4.1
19
export PATH=$FFMPEG_HOME/bin:$PATH
20
#修改完使用命令退出
21
~:wq
22
source /etc/profile
23
# 测试
24
ffmpeg -version
25
~~~~~~~~成功~~~~~~~~~

展开收起

代码展示：#

pom文件#

pom.xml

1
  <parent>
2
    <groupId>org.springframework.boot</groupId>
3
    <artifactId>spring-boot-starter-parent</artifactId>
4
    <version>2.5.4</version>
5
    <relativePath /> <!-- lookup parent from repository -->
6
  </parent>
7

8
  <properties>
9
    <java.version>1.8</java.version>
10
    <javacv.version>1.5.4</javacv.version>
11
    <ffmpeg.version>4.3.1-1.5.4</ffmpeg.version>
12
  </properties>
13

14
  <dependencies>
15

16
    <dependency>
17
      <groupId>commons-lang</groupId>
18
      <artifactId>commons-lang</artifactId>
19
      <version>2.6</version>
20
    </dependency>
21

22
    <dependency>
23
      <groupId>commons-fileupload</groupId>
24
      <artifactId>commons-fileupload</artifactId>
25
      <version>1.2.2</version>
26
    </dependency>
27
    <dependency>
28
      <groupId>commons-io</groupId>
29
      <artifactId>commons-io</artifactId>
30
      <version>2.5</version>
31
    </dependency>
32

33
    <!--web 模块 -->
34
    <dependency>
35
      <groupId>org.springframework.boot</groupId>
36
      <artifactId>spring-boot-starter-web</artifactId>
37
      <exclusions>
38
        <!--排除tomcat依赖 -->
39
        <exclusion>
40
          <artifactId>spring-boot-starter-tomcat</artifactId>
41
          <groupId>org.springframework.boot</groupId>
42
        </exclusion>
43
      </exclusions>
44
    </dependency>
45

46
    <!--undertow容器 -->
47
    <dependency>
48
      <groupId>org.springframework.boot</groupId>
49
      <artifactId>spring-boot-starter-undertow</artifactId>
50
    </dependency>
51

52
    <dependency>
53
      <groupId>org.springframework.boot</groupId>
54
      <artifactId>spring-boot-starter-test</artifactId>
55
      <scope>test</scope>
56
    </dependency>
57

58
    <!--      javacv 和 ffmpeg的依赖包      -->
59
    <dependency>
60
      <groupId>org.bytedeco</groupId>
61
      <artifactId>javacv</artifactId>
62
      <version>${javacv.version}</version>
63
      <exclusions>
64
        <exclusion>
65
          <groupId>org.bytedeco</groupId>
66
          <artifactId>*</artifactId>
67
        </exclusion>
68
      </exclusions>
69
    </dependency>
70

71
    <dependency>
72
      <groupId>org.bytedeco</groupId>
73
      <artifactId>ffmpeg-platform</artifactId>
74
      <version>${ffmpeg.version}</version>
75
    </dependency>
76

77
    <dependency>
78
      <groupId>cn.hutool</groupId>
79
      <artifactId>hutool-all</artifactId>
80
      <version>5.6.5</version>
81
    </dependency>
82

83
    <dependency>
84
      <groupId>log4j</groupId>
85
      <artifactId>log4j</artifactId>
86
      <version>1.2.17</version>
87
    </dependency>
88

89
    <dependency>
90
      <groupId>org.springframework.boot</groupId>
91
      <artifactId>spring-boot-starter-test</artifactId>
92
      <scope>test</scope>
93
    </dependency>
94

95
    <dependency>
96
      <groupId>org.junit.vintage</groupId>
97
      <artifactId>junit-vintage-engine</artifactId>
98
      <scope>test</scope>
99
    </dependency>
100

101
    <dependency>
102
      <groupId>org.springframework.boot</groupId>
103
      <artifactId>spring-boot-starter-web</artifactId>
104
      <exclusions>
105
        <exclusion>
106
          <groupId>org.springframework.boot</groupId>
107
          <artifactId>spring-boot-starter-tomcat</artifactId>
108
        </exclusion>
109
      </exclusions>
110
    </dependency>
111

112
    <dependency>
113
      <groupId>org.springframework.boot</groupId>
114
      <artifactId>spring-boot-starter-undertow</artifactId>
115
    </dependency>
116

117
    <dependency>
118
      <groupId>commons-codec</groupId>
119
      <artifactId>commons-codec</artifactId>
120
    </dependency>
121

122
    <dependency>
123
      <groupId>com.google.code.gson</groupId>
124
      <artifactId>gson</artifactId>
125
    </dependency>
126
  </dependencies>
127
  <build>
128
    <finalName>${project.artifactId}</finalName>
129
    <plugins>
130
      <plugin>
131
        <groupId>org.springframework.boot</groupId>
132
        <artifactId>spring-boot-maven-plugin</artifactId>
133
        <configuration>
134
          <executable>true</executable>
135
        </configuration>
136
      </plugin>
137
    </plugins>
138
  </build>

展开收起

yml配置#

application.yml

1
server:
2
  port: 8086
3

4
app:
5
  # 存储转码视频的文件夹
6
  video-folder: /root/FFmpeg/video_folder
7

8
spring:
9
  servlet:
10
    multipart:
11
      enabled: true
12
      # 不限制文件大小
13
      max-file-size: -1
14
      # 不限制请求体大小
15
      max-request-size: -1
16
      # 临时IO目录
17
      location: "${java.io.tmpdir}"
18
      # 不延迟解析
19
      resolve-lazily: false
20
      # 超过1Mb，就IO到临时目录
21
      file-size-threshold: 1MB
22
  web:
23
    resources:
24
      static-locations:
25
        - "classpath:/static/"
26
        - "file:${app.video-folder}" # 把视频文件夹目录，添加到静态资源目录列表

展开收起

工具类#

MediaInfo

1
package com.nacl.util;
2

3
import java.util.List;
4

5
import com.google.gson.annotations.SerializedName;
6
/**
7
 * @author HAOYANG
8
 * @create 2023-07-29 10:31
9
 */
10
public class MediaInfo {
11
    public static class Format {
12
        @SerializedName("bit_rate")
13
        private String bitRate;
14
        public String getBitRate() {
15
            return bitRate;
16
        }
17
        public void setBitRate(String bitRate) {
18
            this.bitRate = bitRate;
19
        }
20
    }
21

22
    public static class Stream {
23
        @SerializedName("index")
24
        private int index;
25

26
        @SerializedName("codec_name")
27
        private String codecName;
28

29
        @SerializedName("codec_long_name")
30
        private String codecLongame;
31

32
        @SerializedName("profile")
33
        private String profile;
34
    }
35

36
    @SerializedName("streams")
37
    private List<Stream> streams;
38

39
    @SerializedName("format")
40
    private Format format;
41

42
    public List<Stream> getStreams() {
43
        return streams;
44
    }
45

46
    public void setStreams(List<Stream> streams) {
47
        this.streams = streams;
48
    }
49

50
    public Format getFormat() {
51
        return format;
52
    }
53

54
    public void setFormat(Format format) {
55
        this.format = format;
56
    }
57
}

展开收起

TranscodeConfig

1
package com.nacl.util;
2

3
import lombok.Data;
4
/**
5
 * @author HAOYANG
6
 * @create 2023-07-29 10:32
7
 */
8
@Data
9
public class TranscodeConfig {
10

11
    private String poster = "00:00:00.001";        // 截取封面的时间      HH:mm:ss.[SSS]
12
    private String tsSeconds = "15";      // ts分片大小，单位是秒
13
    private String cutStart;      // 视频裁剪，开始时间    HH:mm:ss.[SSS]
14
    private String cutEnd;        // 视频裁剪，结束时间    HH:mm:ss.[SSS]
15
    public String getPoster() {
16
        return poster;
17
    }
18

19
    public void setPoster(String poster) {
20
        this.poster = poster;
21
    }
22

23
    public String getTsSeconds() {
24
        return tsSeconds;
25
    }
26

27
    public void setTsSeconds(String tsSeconds) {
28
        this.tsSeconds = tsSeconds;
29
    }
30

31
    public String getCutStart() {
32
        return cutStart;
33
    }
34

35
    public void setCutStart(String cutStart) {
36
        this.cutStart = cutStart;
37
    }
38

39
    public String getCutEnd() {
40
        return cutEnd;
41
    }
42

43
    public void setCutEnd(String cutEnd) {
44
        this.cutEnd = cutEnd;
45
    }
46

47
    @Override
48
    public String toString() {
49
        return "TranscodeConfig [poster=" + poster + ", tsSeconds=" + tsSeconds + ", cutStart=" + cutStart + ", cutEnd="
50
                + cutEnd + "]";
51
    }
52
}

展开收起

FFmpegUtils

1
package com.nacl.util;
2

3
import java.io.BufferedReader;
4
import java.io.File;
5
import java.io.IOException;
6
import java.io.InputStreamReader;
7
import java.nio.charset.StandardCharsets;
8
import java.nio.file.Files;
9
import java.nio.file.Path;
10
import java.nio.file.Paths;
11
import java.nio.file.StandardOpenOption;
12
import java.security.NoSuchAlgorithmException;
13
import java.time.LocalDate;
14
import java.time.format.DateTimeFormatter;
15
import java.util.*;
16

17
import javax.crypto.KeyGenerator;
18

19
import org.apache.commons.codec.binary.Hex;
20
import org.slf4j.Logger;
21
import org.slf4j.LoggerFactory;
22
import org.springframework.http.HttpStatus;
23
import org.springframework.http.ResponseEntity;
24
import org.springframework.util.StringUtils;
25

26
import com.google.gson.Gson;
27
import org.springframework.web.bind.annotation.RequestPart;
28
import org.springframework.web.multipart.MultipartFile;
29
/**
30
 * @author HAOYANG
31
 * @create 2023-07-29 10:33
32
 */
33

34
public class FFmpegUtils {
35

36
    private static final Logger LOGGER = LoggerFactory.getLogger(FFmpegUtils.class);
37

38
    // 跨平台换行符
39
    private static final String LINE_SEPARATOR = System.getProperty("line.separator");
40

41
    /**
42
     * 生成随机16个字节的AESKEY
43
     * @return
44
     */
45
    private static byte[] genAesKey ()  {
46
        try {
47
            KeyGenerator keyGenerator = KeyGenerator.getInstance("AES");
48
            keyGenerator.init(128);
49
            return keyGenerator.generateKey().getEncoded();
50
        } catch (NoSuchAlgorithmException e) {
51
            return null;
52
        }
53
    }
54

55
    /**
56
     * 在指定的目录下生成key_info, key文件，返回key_info文件
57
     * @param folder
58
     * @throws IOException
59
     */
60
    private static Path genKeyInfo(String folder) throws IOException {
61
        // AES 密钥
62
        byte[] aesKey = genAesKey();
63
        // AES 向量
64
        String iv = Hex.encodeHexString(genAesKey());
65

66
        // key 文件写入
67
        Path keyFile = Paths.get(folder, "key");
68
        Files.write(keyFile, aesKey, StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
69

70
        // key_info 文件写入
71
        StringBuilder stringBuilder = new StringBuilder();
72
        stringBuilder.append("key").append(LINE_SEPARATOR);          // m3u8加载key文件网络路径
73
        stringBuilder.append(keyFile.toString()).append(LINE_SEPARATOR);  // FFmeg加载key_info文件路径
74
        stringBuilder.append(iv);                      // ASE 向量
75

76
        Path keyInfo = Paths.get(folder, "key_info");
77

78
        Files.write(keyInfo, stringBuilder.toString().getBytes(), StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
79

80
        return keyInfo;
81
    }
82

83
    /**
84
     * 指定的目录下生成 master index.m3u8 文件
85
     * @param file      master m3u8文件地址
86
     * @param indexPath      访问子index.m3u8的路径
87
     * @param bandWidth      流码率
88
     * @throws IOException
89
     */
90
    private static void genIndex(String file, String indexPath, String bandWidth) throws IOException {
91
        StringBuilder stringBuilder = new StringBuilder();
92
        stringBuilder.append("#EXTM3U").append(LINE_SEPARATOR);
93
        stringBuilder.append("#EXT-X-STREAM-INF:BANDWIDTH=" + bandWidth).append(LINE_SEPARATOR);  // 码率
94
        stringBuilder.append(indexPath);
95
        Files.write(Paths.get(file), stringBuilder.toString().getBytes(StandardCharsets.UTF_8), StandardOpenOption.CREATE, StandardOpenOption.TRUNCATE_EXISTING);
96
    }
97

98
    /**
99
     * 转码视频为m3u8
100
     * @param source        源视频
101
     * @param destFolder      目标文件夹
102
     * @param config        配置信息
103
     * @throws IOException
104
     * @throws InterruptedException
105
     */
106
    public static void transcodeToM3u8(String source, String destFolder, TranscodeConfig config) throws IOException, InterruptedException {
107

108
        // 判断源视频是否存在
109
        if (!Files.exists(Paths.get(source))) {
110
            throw new IllegalArgumentException("文件不存在：" + source);
111
        }
112

113
        // 创建工作目录
114
        Path workDir = Paths.get(destFolder, "ts");
115
        Files.createDirectories(workDir);
116

117
        // 在工作目录生成KeyInfo文件
118
        Path keyInfo = genKeyInfo(workDir.toString());
119

120
        // 构建命令
121
        List<String> commands = new ArrayList<>();
122
        commands.add("ffmpeg");
123
        commands.add("-i")            ;commands.add(source);          // 源文件
124
        commands.add("-c:v")          ;commands.add("libx264");        // 视频编码为H264
125
        commands.add("-c:a")          ;commands.add("copy");          // 音频直接copy
126
        commands.add("-hls_key_info_file")    ;commands.add(keyInfo.toString());    // 指定密钥文件路径
127
        commands.add("-hls_time")        ;commands.add(config.getTsSeconds());  // ts切片大小
128
        commands.add("-hls_playlist_type")    ;commands.add("vod");          // 点播模式
129
        commands.add("-hls_segment_filename")  ;commands.add("%06d.ts");        // ts切片文件名称
130

131
        if (StringUtils.hasText(config.getCutStart())) {
132
            commands.add("-ss")          ;commands.add(config.getCutStart());  // 开始时间
133
        }
134
        if (StringUtils.hasText(config.getCutEnd())) {
135
            commands.add("-to")          ;commands.add(config.getCutEnd());    // 结束时间
136
        }
137
        commands.add("index.m3u8");                            // 生成m3u8文件
138

139
        // 构建进程
140
        Process process = new ProcessBuilder()
141
                .command(commands)
142
                .directory(workDir.toFile())
143
                .start()
144
                ;
145

146
        // 读取进程标准输出
147
        new Thread(() -> {
148
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
149
                String line = null;
150
                while ((line = bufferedReader.readLine()) != null) {
151
                    LOGGER.info(line);
152
                }
153
            } catch (IOException e) {
154
            }
155
        }).start();
156

157
        // 读取进程异常输出
158
        new Thread(() -> {
159
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getErrorStream()))) {
160
                String line = null;
161
                while ((line = bufferedReader.readLine()) != null) {
162
                    LOGGER.info(line);
163
                }
164
            } catch (IOException e) {
165
            }
166
        }).start();
167

168

169
        // 阻塞直到任务结束
170
        if (process.waitFor() != 0) {
171
            throw new RuntimeException("视频切片异常");
172
        }
173

174
        // 切出封面
175
        if (!screenShots(source, String.join(File.separator, destFolder, "poster.jpg"), config.getPoster())) {
176
            throw new RuntimeException("封面截取异常");
177
        }
178

179
        // 获取视频信息
180
        final MediaInfo[] mediaInfo = {getMediaInfo(source)};
181
        if (mediaInfo[0] == null) {
182
            throw new RuntimeException("获取媒体信息异常");
183
        }
184

185
        // 生成index.m3u8文件
186
        genIndex(String.join(File.separator, destFolder, "index.m3u8"), "ts/index.m3u8", mediaInfo[0].getFormat().getBitRate());
187

188
        // 删除keyInfo文件
189
        Files.delete(keyInfo);
190
    }
191

192
    /**
193
     * 获取视频文件的媒体信息
194
     * @param source
195
     * @return
196
     * @throws IOException
197
     * @throws InterruptedException
198
     */
199
    public static MediaInfo getMediaInfo(String source) throws IOException, InterruptedException {
200
        List<String> commands = new ArrayList<>();
201
        commands.add("ffprobe");
202
        commands.add("-i")        ;commands.add(source);
203
        commands.add("-show_format");
204
        commands.add("-show_streams");
205
        commands.add("-print_format")  ;commands.add("json");
206

207
        Process process = new ProcessBuilder(commands)
208
                .start();
209

210
        MediaInfo mediaInfo = null;
211

212
        try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
213
            mediaInfo = new Gson().fromJson(bufferedReader, MediaInfo.class);
214
        } catch (IOException e) {
215
            e.printStackTrace();
216
        }
217

218
        if (process.waitFor() != 0) {
219
            return null;
220
        }
221

222
        return mediaInfo;
223
    }
224

225
    /**
226
     * 截取视频的指定时间帧，生成图片文件
227
     * @param source    源文件
228
     * @param file      图片文件
229
     * @param time      截图时间 HH:mm:ss.[SSS]
230
     * @throws IOException
231
     * @throws InterruptedException
232
     */
233
    public static boolean screenShots(String source, String file, String time) throws IOException, InterruptedException {
234

235
        List<String> commands = new ArrayList<>();
236
        commands.add("ffmpeg");
237
        commands.add("-i")        ;commands.add(source);
238
        commands.add("-ss")        ;commands.add(time);
239
        commands.add("-y");
240
        commands.add("-q:v")      ;commands.add("1");
241
        commands.add("-frames:v")    ;commands.add("1");
242
        commands.add("-f");        ;commands.add("image2");
243
        commands.add(file);
244

245
        Process process = new ProcessBuilder(commands)
246
                .start();
247

248
        // 读取进程标准输出
249
        new Thread(() -> {
250
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getInputStream()))) {
251
                String line = null;
252
                while ((line = bufferedReader.readLine()) != null) {
253
                    LOGGER.info(line);
254
                }
255
            } catch (IOException e) {
256
            }
257
        }).start();
258

259
        // 读取进程异常输出
260
        new Thread(() -> {
261
            try (BufferedReader bufferedReader = new BufferedReader(new InputStreamReader(process.getErrorStream()))) {
262
                String line = null;
263
                while ((line = bufferedReader.readLine()) != null) {
264
                    LOGGER.error(line);
265
                }
266
            } catch (IOException e) {
267
            }
268
        }).start();
269

270
        return process.waitFor() == 0;
271
    }
272
}

展开收起

controller调用#

UploadController

1
package com.nacl.controller;
2

3
/**
4
 * @author HAOYANG
5
 * @create 2023-07-29 10:33
6
 */
7
import java.io.IOException;
8
import java.nio.file.Files;
9
import java.nio.file.Path;
10
import java.nio.file.Paths;
11
import java.time.LocalDate;
12
import java.time.format.DateTimeFormatter;
13
import java.util.HashMap;
14
import java.util.Map;
15
import java.util.UUID;
16

17
import lombok.extern.slf4j.Slf4j;
18
import org.slf4j.Logger;
19
import org.slf4j.LoggerFactory;
20
import org.springframework.beans.factory.annotation.Value;
21
import org.springframework.http.HttpStatus;
22
import org.springframework.http.ResponseEntity;
23
import org.springframework.web.bind.annotation.*;
24
import org.springframework.web.multipart.MultipartFile;
25
import com.nacl.util.TranscodeConfig;
26
import  com.nacl.util.FFmpegUtils;
27

28
import static com.nacl.util.FFmpegUtils.transcodeToM3u8;
29

30
@Slf4j
31
@RestController
32
@RequestMapping("/uploadController")
33
public class UploadController {
34

35
    @Value("${app.video-folder}")
36
    private String videoFolder;
37

38
    private Path tempDir = Paths.get(System.getProperty("java.io.tmpdir"));
39

40
    /**
41
     * 上传视频进行切片处理，返回访问路径
42
     * @param video
43
     * @param transcodeConfig
44
     * @return
45
     * @throws IOException
46
     */
47
    @PostMapping("/upload")
48
    @CrossOrigin
49
    public Object upload (@RequestPart(name = "file", required = true) MultipartFile video,
50
                          @RequestPart(name = "config", required = true) TranscodeConfig transcodeConfig) throws IOException {
51
        log.info("文件信息：title={}, size={}", video.getOriginalFilename(), video.getSize());
52
        log.info("转码配置：{}", transcodeConfig);
53

54
        // 原始文件名称，也就是视频的标题
55
        String title = video.getOriginalFilename();
56

57
        // io到临时文件
58
        Path tempFile = tempDir.resolve(title);
59
        log.info("io到临时文件：{}", tempFile.toString());
60

61
        try {
62
            video.transferTo(tempFile);
63

64
            // 删除后缀
65
            title = title.substring(0, title.lastIndexOf(".")) + "-" + UUID.randomUUID().toString().replaceAll("-", "");
66

67
            // 按照日期生成子目录
68
            String today = DateTimeFormatter.ofPattern("yyyyMMdd").format(LocalDate.now());
69

70
            // 尝试创建视频目录
71
            Path targetFolder = Files.createDirectories(Paths.get(videoFolder, today, title));
72

73
            log.info("创建文件夹目录：{}", targetFolder);
74
            Files.createDirectories(targetFolder);
75

76
            // 执行转码操作
77
            log.info("开始转码");
78
            try {
79
                transcodeToM3u8(tempFile.toString(), targetFolder.toString(), transcodeConfig);
80
            } catch (Exception e) {
81
                log.error("转码异常：{}", e.getMessage());
82
                Map<String, Object> result = new HashMap<>();
83
                result.put("success", false);
84
                result.put("message", e.getMessage());
85
                return ResponseEntity.status(HttpStatus.INTERNAL_SERVER_ERROR).body(result);
86
            }
87

88
            // 封装结果
89
            Map<String, Object> videoInfo = new HashMap<>();
90
            videoInfo.put("title", title);
91
            videoInfo.put("m3u8", String.join("/", "", today, title, "index.m3u8"));
92
            videoInfo.put("poster", String.join("/", "", today, title, "poster.jpg"));
93

94
            //返回数据
95
            Map<String, Object> result = new HashMap<>();
96
            result.put("success", true);
97
            result.put("data", videoInfo);
98
            return result;
99
        } finally {
100
            // 始终删除临时文件
101
            Files.delete(tempFile);
102
        }
103
    }
104
}

展开收起

Url转换MultipartFile的工具类#

如controller中参数传的是URL 使用以下工具类转换一下即可#

UrlToMultipartFile

1
package com.nacl.util;
2

3
import org.apache.commons.fileupload.FileItem;
4
import org.apache.commons.fileupload.FileItemFactory;
5
import org.apache.commons.fileupload.disk.DiskFileItemFactory;
6
import org.apache.commons.lang.RandomStringUtils;
7
import org.slf4j.Logger;
8
import org.slf4j.LoggerFactory;
9
import org.springframework.web.multipart.MultipartFile;
10
import org.springframework.web.multipart.commons.CommonsMultipartFile;
11

12
import java.io.*;
13
import java.net.HttpURLConnection;
14
import java.net.URL;
15

16
/**
17
 * @author HAOYANG
18
 * @create 2023-07-29 10:36
19
 */
20
public class UrlToMultipartFile {
21

22
    private static final Logger LOGGER = LoggerFactory.getLogger(UrlToMultipartFile.class);
23

24
    /**
25
     * inputStream 转 File
26
     */
27
    public static File inputStreamToFile(InputStream ins, String name) throws Exception{
28
        //System.getProperty("java.io.tmpdir")临时目录+File.separator目录中间的间隔符+文件名
29
        File file = new File(System.getProperty("java.io.tmpdir") + File.separator + name);
30
        OutputStream os = new FileOutputStream(file);
31
        int bytesRead;
32
        int len = 8192;
33
        byte[] buffer = new byte[len];
34
        while ((bytesRead = ins.read(buffer, 0, len)) != -1) {
35
            os.write(buffer, 0, bytesRead);
36
        }
37
        os.close();
38
        ins.close();
39
        return file;
40
    }
41

42
    /**
43
     * file转multipartFile
44
     */
45
    public static MultipartFile fileToMultipartFile(File file) {
46
        FileItemFactory factory = new DiskFileItemFactory(16, null);
47
        FileItem item=factory.createItem(file.getName(),"text/plain",true,file.getName());
48
        int bytesRead = 0;
49
        byte[] buffer = new byte[8192];
50
        try {
51
            FileInputStream fis = new FileInputStream(file);
52
            OutputStream os = item.getOutputStream();
53
            while ((bytesRead = fis.read(buffer, 0, 8192)) != -1) {
54
                os.write(buffer, 0, bytesRead);
55
            }
56
            os.close();
57
            fis.close();
58
        } catch (IOException e) {
59
            e.printStackTrace();
60
        }
61
        return new CommonsMultipartFile(item);
62
    }
63

64
    //url转MultipartFile
65
    public static MultipartFile urlToMultipartFile(String url) throws Exception {
66
        File file = null;
67
        MultipartFile multipartFile = null;
68
        try {
69
            HttpURLConnection httpUrl = (HttpURLConnection) new URL(url).openConnection();
70
            httpUrl.connect();
71
            file = UrlToMultipartFile.inputStreamToFile(httpUrl.getInputStream(),RandomStringUtils.randomAlphanumeric(8)+".mp4");
72
            LOGGER.info("---------"+file+"-------------");
73

74
            multipartFile = UrlToMultipartFile.fileToMultipartFile(file);
75
            httpUrl.disconnect();
76
        } catch (Exception e) {
77
            e.printStackTrace();
78
        }
79
        return multipartFile;
80
    }
81

82
}

展开收起

Tvbox使用教程

Fri, 19 Dec 2025 00:00:00 GMT

Tvbox简介#

TVBox是一款基于开源项目tvmovie修改的影视APP，它本身是一个空壳，需要用户自己导入接口才能使用，具有强大的功能和兼容性，完全免费且开源。TVBox可以看作是“猫影视TV”的开源版本，并且完美移植了“猫影视TV”的核心功能。

软件下载：链接直达安装包的哈希对比对比一下

1
certutil -hashfile TVBox_takagen99_20250706-1456-arm64-generic-java.apk SHA256

tvbox源地址（现成的）#

http://pandown.pro/tvbox/tvbox.json
https://ghcy.eu.org/https://raw.githubusercontent.com/cyao2q/files/master/m.json

tvbox 自定义源地址（手搓）#

过程：

使用tvbox配置编辑器，将各个采集站的api，变成tvbox识别的json格式的文件
需要一台服务器搭建http服务，提供json格式的文件访问
在tvbox源地址设置这条服务器的json文件访问地址

1. tvbox配置编辑器编辑json文件#

XML#

访问TVBOX接口配置编辑器
img

复制采集站的地址的xml格式的地址（更多采集站信息访问链接直达）

这样就添加好了一个TVBOX的源地址了。

Json#

添加第二个采集站的信息，我们点击采集教程

复制json格式的采集接口的地址

点击添加的按钮

根据上面依次填入信息，这样就添加好了两个采集站的播放源了，需要添加更多的播放源也是相同的操作。

TVBOX的标题设置#

比如需要设置如下图所示的标题

只要在分类中添加，就可以实现。（如果设置的分类名称和采集站不同是不会显示的）

导出配置#

点击“保存”-》复制剪贴板的内容，保存一个tvbox.json格式的文件

2. 搭建http服务#

这里我使用vultr的vps作为演示demo（你也可以在自己的内网部署）

将上面保存的文件（tvbox.json）上传到服务器

使用python3提供HTTP的服务

1
root@vultr:~# python3 -m http.server 80
2
Serving HTTP on 0.0.0.0 port 80 (http://0.0.0.0:80/) ...
3

4
root@vultr:~# sudo nohup python3 -m http.server 80 > /var/log/python-http-server.log 2>&1 &   后台挂起运行
5
[1] 4595
6

7
ps -aux  //查看运行进程信息
8

9
kill -9 PID   //结束进程

能正常访问到配置的json文件。

3. tvbox源地址设置#

在TVBOX中设置，上面配置好的json文件。

等待一会，加载成功了

播放源的切换#

返回设置，点击数据源，这样就可以切换了

TVBOX：DIY 资源库（新手指南）

Mon, 15 Dec 2025 00:00:00 GMT

如何快速简单的制作一个影视仓资源合成库，作为热爱写笔记的小编，在这里分享一下关于个人资源库构建方法的文章。实际上，这个过程相对简单。每个TV源码中都带有相应的示例，只需您稍加细心，依据这些演示示例照虎画猫进行复制即可。言归正传，下面将为大家呈现详细的教程。

小编仅展示代码示例，而不包括具体的资源内容。关于资源库的构建，网络上有许多免费的资源可供参考，有需要的朋友可以根据教程自行搭建自己的资源库。

详情版#

影视仓里的功能组成，依次为爬虫文件地址、前端背景、影视资源、直播源、播放器标签、解析接口、IJK播放器解码、广告拦截，以上都是必备的基础功能，还有一些其他的增强功能就按照自己的需求自定义。

影视仓里的功能组成，依次为爬虫文件地址、前端背景、影视资源、直播源、播放器标签、解析接口、IJK播放器解码、广告拦截，以上都是必备的基础功能，还有一些其他的增强功能就按照自己的需求自定义。

“demo.json”展开收起

1
{
2
  "spider": "https://tvbox.com/custom_spider.jar", //自己的爬虫文件后台地址
3
  "wallpaper": "https://tvbox.com/壁纸.png",  //前端背景的图片地址
4
  "sites": [
5
  {
6
    "key": "茅台", //可默认也可自定义
7
    "name": "茅台资源", //前端显示的资源名称自定义
8
    "type": 3, //Type 0-xml 1-json 2-爬虫源 3-自定义爬虫 4-服务器爬虫
9
    "api": "csp_spider", //默认走爬虫线路都是这个记号不可修改,api必须是csp_开头
10
    "searchable": 1,  //可搜索? 0-不可以 1-可以
11
    "quickSearch": 1, //可快速搜索? 0-不可以 1-可以
12
    "filterable": 1,  //可筛选? 0-不可以 1-可以
13
    "ext": "https://tvbox.com/api.php/app/" //爬虫模式的对接地址
14
  }, //注意增加资源要在逗号之后
15
  {
16
    "key": "红牛",
17
    "name": "红牛资源", //前端显示的资源名称自定义
18
    "type": 0, //Type 0-xml 1-json 2-爬虫源 3-自定义爬虫 4-服务器爬虫
19
    "api": "https://www.hongniuzy2.com/api.php/provide/vod/at/xml/",//默认苹果CMS资源采集站的地址
20
    "playUrl": "https://www.hnjiexi.com/m3u8/?url=", //资源指定JSON解析接口，一般不填写，最好是不要填写
21
    "searchable": 1,  ////可搜索? 0-不可以 1-可以
22
    "quickSearch": 1, //可筛选? 0-不可以 1-可以
23
    "filterable": 1,  //可筛选? 0-不可以 1-可以
24
    "categories": [ "电影","剧集","综艺","动漫","短剧"] //可以在前端显示的分类 注意结尾不要带逗号
25
  },
26
  //这个地方可以继续添加资源，将你从别处复制过来的代码粘贴到这里即可
27
  {
28
   "key": "push_agent",
29
   "name": "前端自定义播放功能", //前端自定义播放链接功能
30
   "type": 3,
31
   "api": "csp_Push",
32
   "searchable": 0,
33
   "quickSearch": 0,
34
   "changeable": 0,
35
   "ext": "http://127.0.0.1:9978/file/MeowTV/token.txt+4k|auto|fhd"
36
  } //注意结尾不要带逗号
37
  ],
38
  "lives": [
39
    {
40
      "name": "live", //名字自定义
41
      "type": 0,
42
      "url": "http://tvbox.com/zhibo.txt", //这里填写直播源的地址（注意要txt结尾的链接）
43
      "playerType": 1,
44
      "ua": "okhttp/3.15",
45
      "epg": "http://epg.112114.xyz/?ch={name}&amp;date={date}",
46
      "logo": "https://epg.112114.xyz/logo/{name}.png"
47
    }
48
  ],
49
  "flags":["lzm3u8","youku","qq","iqiyi","qiyi","letv","sohu","tudou","mgtv","bilibili"], //添加播放器标识用逗号分割
50

51
  "parses":[
52
      {"name": "聚合","type": 3,"url": "Demo"}, //类型
53
      {"name": "轮询","type": 2,"url": "Sequence"}, //类型
54
      {"name": "1号线","type": 0,"url": "https://json解析地址/?url="}, //支持json和普通接口同时使用
55
      {"name": "2号线","type": 0,"url": "https://普通解析地址/?url="}, //解析接口可以无限添加
56
      {"name": "3号线","type": 0,"url": "https://无限解析地址/?url="}  //注意结尾不要带逗号
57
],
58
"ijk": [{"group": "软解码","options": [
59
{"category": 4,"name": "opensles","value": "0"},
60
{"category": 4,"name": "overlay-format","value": "842225234"},
61
{"category": 4,"name": "framedrop","value": "1"},
62
{"category": 4,"name": "soundtouch","value": "1"},
63
{"category": 4,"name": "start-on-prepared","value": "1"},
64
{"category": 1,"name": "http-detect-range-support","value": "0"},
65
{"category": 1,"name": "fflags","value": "fastseek"},
66
{"category": 2,"name": "skip_loop_filter","value": "48"},
67
{"category": 4,"name": "reconnect","value": "1"},
68
{"category": 4,"name": "max-buffer-size","value": "5242880"},
69
{"category": 4,"name": "enable-accurate-seek","value": "0"},
70
{"category": 4,"name": "mediacodec","value": "0"},
71
{"category": 4,"name": "mediacodec-auto-rotate","value": "0"},
72
{"category": 4,"name": "mediacodec-handle-resolution-change","value": "0"},
73
{"category": 4,"name": "mediacodec-hevc","value": "0"},
74
{"category": 1,"name": "dns_cache_timeout","value": "600000000"}]},
75
{"group": "硬解码","options": [
76
{"category": 4,"name": "opensles","value": "0"},
77
{"category": 4,"name": "overlay-format","value": "842225234"},
78
{"category": 4,"name": "framedrop","value": "1"},
79
{"category": 4,"name": "soundtouch","value": "1"},
80
{"category": 4,"name": "start-on-prepared","value": "1"},
81
{"category": 1,"name": "http-detect-range-support","value": "0"},
82
{"category": 1,"name": "fflags","value": "fastseek"},
83
{"category": 2,"name": "skip_loop_filter","value": "48"},
84
{"category": 4,"name": "reconnect","value": "1"},
85
{"category": 4,"name": "max-buffer-size","value": "5242880"},
86
{"category": 4,"name": "enable-accurate-seek","value": "0"},
87
{"category": 4,"name": "mediacodec","value": "1"},
88
{"category": 4,"name": "mediacodec-auto-rotate","value": "1"},
89
{"category": 4,"name": "mediacodec-handle-resolution-change","value": "1"},
90
{"category": 4,"name": "mediacodec-hevc","value": "1"},
91
{"category": 1,"name": "dns_cache_timeout","value": "600000000"}]}],
92
"ads": ["屏蔽广告地址1","屏蔽广告地址2","屏蔽广告地址13"]
93
}...

展开收起

到这里简单的制作一个自己的影视仓资源合成库就完成了，这里就不提供api.json文件和custom_spider.jar文件了，TVBOX或绿豆TV源码应该都有这个示例文件，如意版本的后台应用里也自带一键生成的影视仓功能，其他也没啥可说的了，自己慢慢的研究哈。

极简版#

如果是直接使用影视提供的采集接口，例如：无尽，红牛，茅台等资源采集站，那这个配置就非常的简单

极简版.json展开收起

1
{
2
    "sites": [
3
      {
4
        "key": "茅台",
5
        "name": "茅台资源",
6
        "type": 1,
7
        "api": "https://caiji.maotaizy.cc/api.php/provide/vod/at/josn/",
8
    "playUrl": "https://mtjiexi.cc:966/?url=",  // 解析接口最好是不用填写
9
        "searchable": 1,
10
        "quickSearch": 1,
11
        "filterable": 1,
12
        "categories": [
13
          "电影",
14
          "连续剧",
15
          "综艺片",
16
          "动漫"
17
        ]
18
      },
19
  {
20
      "key": "新浪",
21
      "name": "新浪资源",
22
      "type": 1,
23
      "api": "https://api.xinlangapi.com/xinlangapi.php/provide/vod/",
24
      "searchable": 1,
25
      "quickSearch": 1,
26
      "filterable": 1,
27
      "categories": [
28
        "电影",
29
        "电视剧",
30
        "综艺",
31
        "动漫",
32
    "大陆剧",
33
        "动作片",
34
        "爱情片",
35
        "韩剧"
36
      ]
37
    }
38
  ]
39
}

展开收起

总结#

如果想要自定义采集站，那么需要自行编写对应网站的爬虫，所谓的本地jar包也就是java爬虫所打包构建的

1
{
2
    "spider": "http://你的网站地址/spider.jar;md5;该jar包的md5值",
3
    "sites": [
4
        {
5
            "key": "YingShi01",
6
            "name": "影视01",
7
            "type": 3,
8
            "api": "csp_YingShi01",
9
            "searchable": 1
10
        },
11
        {
12
            "key": "YingShi02",
13
            "name": "影视02",
14
            "type": 3,
15
            "api": "csp_YingShi02",
16
            "searchable": 1,
17
            "spider": "http://你的网站地址/xxx.jar;md5;该jar包的md5值"
18
        }
19
    ]
20
}

展开收起

我个人认为自己私下弄弄玩还可以，毕竟现在网络上已经有很多大佬已经造好了轮子，我们直接使用就行了

这里给大家提供一个综合源：https://upld.zone.id/uploads/q9iq9e5iq/tvboxlvse.json

Spider编写入门指南

Wed, 10 Dec 2025 00:00:00 GMT

Spider编写入门指南#

一、介绍#

本篇主要整理网络中流传的CatVodSpider的编写方式、数据格式，需要阅读者有Java编程基础。

一句话总结：猫影视/TVBox的自定义Spider是通过加载外部jar，通过反射来实例化jar包中的Spider类，并调用Spider对象下的方法实现的。

本模板项目可以配合任意符合TVBox源导入使用

本项目打包出的jar可以直接导入TVBox使用，仅供大家进行技术学习和研究，作者不认可、不支持任何侵犯版权、传播不健康信息或其他违反法律法规的行为，请大家在编写或执行爬虫程序之前，务必确保自己拥有目标数据的版权，或已获得了目标网站或App的官方授权。

二、相关基础类#

com.github.catvod.crawler.Spider是Spider的基类，你需要继承该类，重写（override）其中的核心方法，来编写你的自定义Spider（一个Spider类对应一个站点），自定义的Spider要与Spider基类在同一个包下。

三、Spider类下的各方法及返回数据格式#

猫影视规则下，Spider下的所有核心方法均返回String（json格式的字符串），编写过程中你可能会发现一些不符合Javaer习惯的行为和规范，不过事到如今这套规则已经成了祖宗之法，为了能编写出通用性强的Spider，你需要遵循这些规则。

编写Spider逻辑时，一般做法是：

利用com.github.catvod.net.OkHttp工具类下的方法，从源站点中请求数据，并利用Jsoup等库解析出其中的影视相关数据；
利用com.github.catvod.bean下的实体类，将相关数据组装为java对象，并最终把所有对象组装为一个com.github.catvod.bean.Result对象；
有了com.github.catvod.bean.Result对象后，调用该对象下的string()来把对象转为json字符串并返回。（有性能洁癖的，也可以使用com.github.catvod.utils.Json工具类中的toJson方法）。

下面介绍Spider下的各核心方法。

1. homeContent#

当用户在软件中点选进入某个影视站点时，该方法被调用。方法返回站点的首页数据，包含影视分类数据、影视筛选数据、首页推荐影视数据等。

该方法的参数作用未知，作者没有用到过，可以忽略。

返回的数据格式示例如下：

1
{
2
  "class": [{   // 分类
3
    "type_id": "dianying", // 分类id
4
    "type_name": "电影" // 分类名
5
  }, {
6
    "type_id": "lianxuju",
7
    "type_name": "连续剧"
8
  }],
9
  "filters": { // 筛选
10
    "dianying": [{ // 分类id 就是上面class中的分类id
11
      "key": "0", // 筛选key
12
      "name": "分类", // 筛选名称
13
      "value": [{ // 筛选选项
14
        "n": "全部", // 选项展示的名称
15
        "v": "dianying" // 选项最终在url中的展现
16
      }, {
17
        "n": "动作片",
18
        "v": "dongzuopian"
19
      }]
20
    }],
21
    "lianxuju": [{
22
      "key": 0,
23
      "name": "分类",
24
      "value": [{
25
        "n": "全部",
26
        "v": "lianxuju"
27
      }, {
28
        "n": "国产剧",
29
        "v": "guochanju"
30
      }, {
31
        "n": "港台剧",
32
        "v": "gangtaiju"
33
      }]
34
    }]
35
  },
36
  "list": [{ // 首页最近更新视频列表
37
    "vod_id": "1901", // 视频id
38
    "vod_name": "判决", // 视频名
39
    "vod_pic": "https:\/\/pic.imgdb.cn\/item\/614631e62ab3f51d918e9201.jpg", // 展示图片
40
    "vod_remarks": "6.8" // 视频信息 展示在 视频名上方
41
  }, {
42
    "vod_id": "1908",
43
    "vod_name": "移山的父亲",
44
    "vod_pic": "https:\/\/pic.imgdb.cn\/item\/6146fab82ab3f51d91c01af1.jpg",
45
    "vod_remarks": "6.7"
46
  }]
47
}

展开收起

其中，每个json属性和实体类的对应关系为：

class：List<com.github.catvod.bean.Class>
filters：Map<String, List<com.github.catvod.bean.Filter>>
list：List<com.github.catvod.bean.Vod>

2. categoryContent#

当用户在某个站点中点击某个影视分类、进行条件筛选、进行翻页动作时，该方法被调用。方法返回一个影视数据列表和相关的分页信息。

该方法的参数列表如下：

tid：影视的分类id，在homeContent部分已有提到；
pg：分页的页号，默认为”1”，随每次翻页递增；
filter：是否使用了条件筛选，如果该项为false，则可以无视下面的extend属性，不处理条件筛选逻辑；
extend：用户进行条件筛选时，该参数为“filter key”和“filter value”的键值对（关于filter，已经在homeConent中介绍过了）。

返回的数据格式示例如下：

1
{
2
  "page": 1, // 当前页
3
  "pagecount": 2, // 总共几页
4
  "limit": 60, // 每页几条数据
5
  "total": 120, // 总共多少调数据
6
  "list": [{ // 视频列表 下面的视频结构 同上面homeContent中的
7
    "vod_id": "1897",
8
    "vod_name": "北区侦缉队",
9
    "vod_pic": "https:\/\/pic.imgdb.cn\/item\/6145d4b22ab3f51d91bd98b6.jpg",
10
    "vod_remarks": "7.3"
11
  }, {
12
    "vod_id": "1879",
13
    "vod_name": "浪客剑心 最终章 人诛篇",
14
    "vod_pic": "https:\/\/pic.imgdb.cn\/item\/60e3f37e5132923bf82ef95e.jpg",
15
    "vod_remarks": "8.0"
16
  }]
17
}

展开收起

其中，每个json属性和实体类的对应关系为：

list：List<com.github.catvod.bean.Vod>

需尽量保证分页信息完整、正确，如若无法获取到完整的分页信息，至少应将limit设置为list列表的长度，将pagecount和total设置为一个足够大的数值（如Integer.MAX_VALUE），以确保软件通过此数据能够进行正常的分页动作。

3. detailContent#

当用户点选某个影视，进入影视详情页时，此方法被调用。方法返回影视的详情信息。

该方法的参数列表如下：

ids：影视id。虽然不知道为什么是一个List，一般取第一个元素来用即可。

返回的数据格式示例如下：

1
{
2
  "list": [{
3
    "vod_id": "1902",
4
    "vod_name": "海岸村恰恰恰",
5
    "vod_pic": "https:\/\/pic.imgdb.cn\/item\/61463fd12ab3f51d91a0f44d.jpg",
6
    "type_name": "剧情",
7
    "vod_year": "2021",
8
    "vod_area": "韩国",
9
    "vod_remarks": "更新至第8集",
10
    "vod_actor": "申敏儿,金宣虎,李相二,孔敏晶,徐尚沅,禹美华,朴艺荣,李世亨,边胜泰,金贤佑,金英玉",
11
    "vod_director": "柳济元",
12
    "vod_content": "海岸村恰恰恰剧情:　　韩剧海岸村恰恰恰 갯마을 차차차改编自2004年的电影《我的百事通男友洪班长》，海岸村恰恰恰 갯마을 차차차讲述来自大都市的牙医（申敏儿 饰）到充满人情味的海岸村开设牙医诊所，那里住着一位各方面都",
13
        // 播放源 多个用$$$分隔
14
    "vod_play_from": "qiepian$$$yun3edu",
15
        // 播放列表 注意分隔符 分别是 多个源$$$分隔，源中的剧集用#分隔，剧集的名称和地址用$分隔
16
    "vod_play_url": "第1集$1902-1-1#第2集$1902-1-2#第3集$1902-1-3#第4集$1902-1-4#第5集$1902-1-5#第6集$1902-1-6#第7集$1902-1-7#第8集$1902-1-8$$$第1集$1902-2-1#第2集$1902-2-2#第3集$1902-2-3#第4集$1902-2-4#第5集$1902-2-5#第6集$1902-2-6#第7集$1902-2-7#第8集$1902-2-8"
17
  }]
18
}

展开收起

其中，每个json属性和实体类的对应关系为：

list：List<com.github.catvod.bean.Vod>

（就获取单个影片详情这个场景来说，list中只包含一个影片对象即可。）

影片的一些元信息（导演、演员、年份等）可以省略，但至少应确保影片id（vod_id），播放源（vod_play_from）和播放列表（vod_play_url）有数据。

4. searchContent#

当用户输入关键字进行影视搜索时，该方法会被调用。方法返回一个影视列表。

注意，该方法有参数不同的重载，都需要进行重写，但逻辑一般使用同一个，调用相同的代码即可，

该方法的参数列表如下：

key：搜索关键字；
quick：是否使用了快速搜索。是TVBox中使用到的参数，重要性较低，可以忽略；
pg：分页的页号。固定为”1”，一般在搜索中无需支持翻页，可以忽略。

返回的数据格式示例如下：

1
{
2
  "list": [{ // 视频列表 下面的视频结构 同上面homeContent中的
3
    "vod_id": "1606",
4
    "vod_name": "陪你一起长大",
5
    "vod_pic": "https:\/\/img.aidi.tv\/img\/upload\/vod\/20210417-1\/e27d4eb86f7cde375171dd324b2c19ae.jpg",
6
    "vod_remarks": "更新至第37集"
7
  }]
8
}

其中，每个json属性和实体类的对应关系为：

list：List<com.github.catvod.bean.Vod>

5. playerContent#

用户在影片详情页中点击其中一个剧集，进行影片播放时，该方法被调用。方法返回一个可播放的网络媒体地址（mp4、m3u8等）。

该方法的参数列表如下：

flag：含义未知，作者没用到过，可以忽略；
id：剧集id。在detailContent部分中，有列出影片的vod_play_url属性，比如“第1集$1902-1-1#第2集$1902-1-2”，“第1集”的剧集id就是“1902-1-1”，“第2集”的剧集id就是“1902-1-2”（有的作者喜欢把剧集id直接设置为该剧集播放页面的url，这样获取播放地址比较方便）
vipFlags: 含义未知，作者没用到过，暂时忽略，用到时再考虑完善这个吧。

只有一个url属性需要返回，就不列json数据示例了，返回Result.get().url(url).string()即可。

四、打包和配置#

实现了上述核心方法后，Spider就可以打包使用了。

直接调用gradle的jar就能打包了，打包后，你会在build目录下得到一个spider.jar，同时得到一个该jar包的md5值。

接下来是根据猫影视规则，编写一个可以被软件导入的json配置文件，并把jar包的地址设置在里面。

以下是一个简洁的示例（假设我们为2个站点写了Spider类，分别为“YingShi01”和“YingShi02”，更多的站点就以此类推）：

1
{
2
    "spider": "http://你的网站地址/spider.jar;md5;该jar包的md5值",
3
    "sites": [
4
        {
5
            "key": "YingShi01",
6
            "name": "影视01",
7
            "type": 3,
8
            "api": "csp_YingShi01",
9
            "searchable": 1
10
        },
11
        {
12
            "key": "YingShi02",
13
            "name": "影视02",
14
            "type": 3,
15
            "api": "csp_YingShi02",
16
            "searchable": 1,
17
            "spider": "http://你的网站地址/xxx.jar;md5;该jar包的md5值"
18
        }
19
    ]
20
}

展开收起

其中：

spider：我们的jar包地址，除了网络地址之外，也可以设置为“file:///”开头的本地文件地址。至于md5部分，可以设置也可以省略，但推荐设置，可以提升性能。
```
1
sites
```
：显示在软件中的影视站点列表
- key：站点key。可以任意设置，但要保证每个站点的key是唯一的；
- name：站点名称。可以任意设置；
- type：固定为3，对应的就是我们编写的Spider类型；
- api：用于反射调用Spider类。固定设置为“csp_类名”，比如Spider类名为“YingShi01”，就设置为“csp_YingShi01”；
- searchable：是否支持影视搜索。如果不支持影视搜索，可以设置为0，软件在搜索影视时就会略过该站点；
- spider：如果该站点需要使用独立的jar包，而非上面统一设置的spider，可以指定该属性。

另外，上面的一些资料中包含了带有注释的json，但仅仅是为了展示方便，在实际情况中大家不要在json文件中书写注释！json是一种数据交换格式，只应该包含数据结构（数组和对象），不应该包含非数据内容。虽然带有注释的json仍可被一些json库解析，但这归根结底是不符合其设计规范的，可能会导致问题。

Uni-App（Vue3 + TypeScript）方案结构详解

Fri, 28 Nov 2025 00:00:00 GMT

在本文中，我们将详细解析一个完整的 Uni-App + Vue3 + TypeScript工程结构。带你了解每个文件、目录的用途与作用。

项目结构总览#

项目结构展开收起

1
UNIAPP-项目名称/
2
├─ .idea/                  # VSCode / WebStorm 项目配置文件
3
├─ dist/                   # 打包输出目录（编译后的文件）
4
├─ node_modules/           # 第三方依赖库（由 npm 自动生成）
5
├─ src/                    # 核心源代码目录
6
│  ├─ api/                 # 与后端通信的接口封装
7
│  ├─ components/          # 自定义 Vue 组件
8
│  ├─ hooks/               # 封装的组合式函数（Composition API）
9
│  ├─ pages/               # 应用页面（每个文件夹代表一个页面）
10
│  ├─ static/              # 静态资源（图片、音频、字体等）
11
│  ├─ store/               # 全局状态管理（Pinia 或 Vuex）
12
│  ├─ utils/               # 工具函数模块（时间格式化、节流、防抖等）
13
│  ├─ App.vue              # 应用根组件
14
│  ├─ env.d.ts             # 环境类型声明文件（用于全局类型补充）
15
│  ├─ main.ts              # 应用入口文件（创建 Vue 应用实例）
16
│  └─ manifest.json        # Uni-App 运行配置文件（App 权限、启动图等）
17
│
18
├─ pages.json              # 页面配置文件（页面路径与导航栏）
19
├─ shime-uni.d.ts          # Uni-App 全局类型声明文件（为 `uni.*` 提供类型提示）
20
├─ uni.scss                # 全局样式变量文件（颜色、字体、间距）
21
├─ .gitignore              # Git 忽略文件列表
22
├─ eslint.config.mjs       # ESLint 代码规范配置
23
├─ index.html              # Web 平台入口 HTML 文件（H5 编译时使用）
24
├─ package-lock.json       # npm 依赖锁定文件（自动生成）
25
├─ package.json            # 项目信息与依赖声明（最核心的配置）
26
├─ README.md               # 项目说明文档
27
├─ shims-uni.d.ts          # 兼容不同平台的 Uni 类型声明
28
├─ tsconfig.json           # TypeScript 编译配置文件
29
└─ vite.config.ts          # Vite 构建工具配置文件

展开收起

各目录与文件详解#

1️⃣ `.idea/`#

由 JetBrains（WebStorm、PhpStorm）自动生成，保存 IDE工程设置，不参与构建。

2️⃣ `dist/`#

项目打包后生成的产物目录。通常不会手动编辑，发布或部署时使用。

3️⃣ `node_modules/`#

项目依赖安装后生成的模块目录，包含所有 npm 包。

4️⃣ `src/` ------ 项目核心代码目录#

`api/`#

用于封装与后端通信的接口模块，示例：

demo

1
import request from '@/utils/request'
2
export const getUserList = () => request.get('/user/list')

`components/`#

放置全局或局部可复用的 Vue 组件，例如：

`hooks/`#

自定义组合式函数目录，用于抽离通用逻辑：

1
export function useCounter() {
2
const count = ref(0)
3
const increment = () => count.value++
4
return { count, increment }
5
}

`pages/`#

每个文件夹代表一个独立页面，例如：

1
pages/
2
├─ index/
3
│  └─ index.vue
4
├─ login/
5
│  └─ login.vue

`static/`#

放置不会被 Webpack/Vite 处理的静态资源（如图片、音频）。

`store/`#

用于状态管理，可采用 Pinia：

1
import { defineStore } from 'pinia'
2
export const useUserStore = defineStore('user', {
3
state: () => ({ name: '张三', token: '' })
4
})

`utils/`#

封装项目常用工具函数：

1
export function formatTime(date: Date) {
2
return date.toLocaleString()
3
}

`App.vue`#

应用根组件，是整个项目的启动入口（类似 React 的 App.js）。

`main.ts`#

项目启动文件，挂载 App 并创建应用实例：

1
import { createSSRApp } from 'vue'
2
import App from './App.vue'
3
export function createApp() {
4
const app = createSSRApp(App)
5
return { app }
6
}

`manifest.json`#

App 端运行配置文件，控制应用图标、启动页、权限等。

5️⃣ `pages.json`#

定义页面路径与导航栏外观，是 UniApp 的”路由表”。

1
{
2
"pages": [ //pages数组中第一项表示应用启动页，参考：https://uniapp.dcloud.io/collocation/pages
3
    {
4
      "path": "pages/index/index",
5
      "style": {
6
        "navigationBarTitleText": "uni-app"
7
      }
8
    }
9
  ]
10
}

6️⃣ `uni.scss`#

全局样式变量文件，例如：

1
$primary-color: #3b82f6;
2
$text-color: #333;

所有 .vue 页面都可直接使用这些变量。

7️⃣ `vite.config.ts`#

Vite 构建配置文件，定义插件与路径别名：

1
import { defineConfig } from 'vite'
2
import uni from '@dcloudio/vite-plugin-uni'
3
import { fileURLToPath, URL } from 'node:url'
4
export default defineConfig({
5
resolve: { alias: { '@': fileURLToPath(new URL('./src', import.meta.url)) } },
6
plugins: [uni()]
7
})

8️⃣ `tsconfig.json`#

TypeScript 的核心配置文件，控制类型检查、语法支持和路径解析：

1
{
2
"compilerOptions": {
3
"target": "ESNext",
4
"strict": true,
5
"baseUrl": ".",
6
"paths": { "@/*": ["./src/*"] }
7
}
8
}

9️⃣ `.eslintrc.cjs / eslint.config.mjs`#

代码规范配置文件，控制 ESLint 行为，比如是否允许多余空格、未使用变量等。

其他文件说明#

文件说明

.gitignore 控制哪些文件不提交到 Git index.html H5 运行入口 package.json 项目依赖、脚本命令 package-lock.json 锁定依赖版本 README.md 项目说明文档 shims-uni.d.ts / env.d.ts 提供 UniApp、环境变量的类型声明

路由封装（和vue用法一致）#

该路由系统基于 Uni-App 与 Vue3 构建，统一封装了页面跳转与参数管理逻辑。它自动解析 URL 中的参数（支持多层 JSON 与编码），并提供类型安全的路由对象。开发者通过 useRouter() 即可在任意页面中获取参数、执行跳转、重定向或返回，简化页面通信与导航流程。

分别负责 URL 拼接 → 参数传递 → 参数解析 → 页面 Hook

基础工具 utils/params.ts 负责把参数对象拼接或解析成 URL 路由核心类 utils/router.ts 封装 uni.navigateTo / redirectTo 等操作参数解析Hook useQuery/index.ts 负责在页面加载时解析 URL 参数并返回响应式对象路由Hook useRouter/index.ts 将 Router 与 useQuery 结合，实现页面级路由对象

1️⃣ params.ts —— URL 参数工具

1
    功能：拼接或解析 URL 参数。
2
    提供函数：
3
    setParams(url, params)：把对象转成 ?a=1&b=2。
4
    getParams(url)：从 URL 提取参数对象。
5
    服务对象：被 router.ts 调用，用来生成跳转链接。

2️⃣ router.ts —— 路由核心类

1
    功能：封装 uni.navigateTo、redirectTo、switchTab、back。
2
    核心点：
3
    统一参数处理（调用 setParams() 拼接）。
4
    维护当前 path 与 query。
5
    提供生命周期回调 ready() / runReady()。
6
    服务对象：被 useRouter.ts 实例化，用来操作页面跳转。

3️⃣ useQuery —— 参数解析 Hook

1
    功能：在页面加载时自动解析 URL 参数。
2
    特性：
3
    两次 decodeURIComponent 解码。
4
    自动识别 JSON 并递归解析。
5
    支持合并默认值。
6
    输出：返回响应式对象 query。
7
    服务对象：被 useRouter.ts 调用，用于读取当前页参数。

4️⃣ useRouter —— 页面路由 Hook（整合层）

1
    功能：把 Router + useQuery 结合成页面可直接使用的路由对象。
2
    逻辑：
3
    创建 query = useQuery()；
4
    创建响应式 router = new Router()；
5
    在 onLoad 时写入 query 和当前路径；
6
    页面渲染完成后执行 router.runReady() 回调。
7
    输出：一个带跳转功能、含当前参数的 router 实例。

四者协作流程

Terminal window

1
    页面加载
2
        ↓
3
        useRouter()
4
        ├─ 调用 useQuery() → 解析 URL 参数
5
        ├─ 创建 Router() → 管理跳转与状态
6
        ├─ 写入 query/path
7
        └─ nextTick → runReady() 触发回调

✅ 一句话总结：

1
params.ts 负责拼接，router.ts 负责跳转，
2
useQuery 负责解析，useRouter 负责整合。
3
页面通过 useRouter() 一步即可完成「参数解析 + 路由操作」。

总结#

Lighting-UniApp 是一个基于 Vue3 + TypeScript + Uni-App 的跨平台项目，通过 vite 构建、tsconfig.json 提供类型支持、pages.json 控制页面结构、manifest.json 管理应用权限。

这一结构清晰、模块划分明确的项目架构，非常适合前端工程化与移动端多端开发。

✨ 作者建议：写项目时，保持 api、store、utils 的独立性；保持 pages.json 的整洁，可以让你的 UniApp 项目结构清晰、易维护。

JetBrains 产品激活失败原因整理和解决方法？常见问题整理

Wed, 26 Nov 2025 00:00:00 GMT

JetBrains 产品激活失败原因整理和解决方法？常见问题整理#

激活工具目前已支持最新版本的激活，结合大家之前在激活时，激活失败的一些共性问题，整理了一篇文章，方便大家排查，大家按着解决就可以了。

一、激活时间问题#

1、激活后，显示激活时间到2026年#

答：已经激活成功。显示激活时间到(2025/2026)年，说明IDE已经激活了，不用在意激活时间，时间是可以调整的，IDE激活了就可以免费使用。

二、激活失败，常见错误#

1、key无效/密钥无效#

img

答：提示Key无效，说明工具没有生效，或者不支持当前版本

a、先排查自己的IDE版本是否支持（本激活工具需2021.3以上版本，低于该版本无法激活）和激活工具是否为最新版本

b、重新执行激活脚本，并重启电脑，重启IDE，看是否生效，一般可以解决问题

c、如果还是无法生效，请手动配置激活工具（添加javaagent路径）

2、xxx.jar Not Found#

答：激活工具没解压，或者解压方式不对

a、工具打包为zip格式，需要先解压，尤其Windows用户，不要直接双击进入执行脚本，会提示找不到jar文件

b、在wx聊天存放路径下直接解压，wx路径有保护，会提示找不到，建议将文件单独保存一个目录（路径不要有中文汉字和特殊符号）

c、如果上面都对，那就是JDK没安装，找不到jar文件，请先安装JDK

3、报错：“Cannot collect JVM options，Cannot read…，stream did not contain valid UTF-8”异常#

答：最近遇到不少这个错误的，很明显，编码出问题了，建议激活工具存放路径不要有中文汉字和特殊符号

首先找到该文件所在位置，用记事本打开看是不是utf-8格式

IDEA 2024.3.1.1 最新破解版安装教程（附激活码，至2099年）-氯化钠资源网站

将文件编码修改为 UTF-8，注意检查是否有乱码。如果发现乱码，则需要将路径更换为全英文路径，即插件所在的路径。在下面这张图中找到红框中的 .jar 文件，将其移动到全英文路径下，然后将新路径替换到图中的红框位置。

IDEA 2024.3.1.1 最新破解版安装教程（附激活码，至2099年）-氯化钠资源网站

原来的插件的路径在c盘下，一般user为中文名就会乱码，我的方法是将找到c盘下路径的插件，复制到d盘，将文件中的插件路径改成d盘的英文路径

4、许可证过期/无效，提示：“许可证无法验证”#

原因：出现这个问题，一般是新版本2024.2居多，这是因为官方加入了区域限制，比如原来官方的许可证验证域名是：account.jetbrains.com，而新版本中，根服务器许可证验证地址更换为了，大陆地区：account.jetbrains.com.cn，有了区域区分，造成原来的工具失效的问题。

解决思路1:#

如果是老用户，则可以在设置菜单中来更改（一定要更改）：

解决思路2:#

新版本一般默认的是中国大陆，双击桌面的 IDEA 快捷启动图标，来打开 IDEA 。注意，2024.2 之后的版本，若初次安装，会提示选择所在区域，如下图所示，如果选择了 China Mainland，会在激活的时候反复跳出激活码并提示激活码无效，原因是新版本会拦截 .cn 域名，导致激活许可被吊销，所以，千万不要指定区域！！

5、激活成功后，重启电脑/过一段时间又失效？#

答：原因是激活配置被系统自动重置了。一键激活时，是通过修改本地用户环境变量，添加配置实现破解激活，部分用户装有安全软件（360等），重启电脑后，添加的配置被系统自动重置，删除，造成激活失效，重新激活一遍脚本，再次激活即可，或者手动配置，这样更稳定，不用担心被系统删除。

手动配置激活工具（添加javaagent路径），按此教程添加最新版本的激活工具路径：https://lzphy.top/257/

6、Mac执行脚本报错：“Could not set environment: 150: Operation not permitted while System Integrity Protection is engaged”#

解决思路1：#

关闭SIP需要进入恢复模式，重新启动Mac，然后同时按住“Command”+“R”不放，直到看到苹果的标志再松开，然后等待片刻进入macOS恢复模式。

进入恢复模式后，在顶部菜单点击“实用工具”→“终端”打开终端，拷贝命令“csrutil disable”（不含引号）粘贴进去按回车，返回提示：“System Integrity Protection is off.”即SIP关闭成功。然后点击顶部菜单“”→“重新启动”即可。

解决思路2：#

不通过执行脚本了，也不用修改环境变量，直接手动添加激活工具的配置

7、提示：“This license SGKLY6KOU has been suspended.”#

答：此许可证已经被暂停。说明激活码被官方封了，等网站更新，或者换其他激活方式（也有用户是用了低版本的激活工具无法激活，建议用最新工具）。可以用工具激活或者联系我购买付费版授权。

8、Windows用户执行脚本时提示：“没有权限”#

答：部分Windows用户会出现这个报错提示，可以尝试右键管理员运行脚本；如果右键没有出现管理员选项，那么使用系统管理员运行CMD窗口，找到激活脚本位置

d2b5ca33bd20250110145036

9、Unable to Save Data Error saving license data；IDEA每次打开总是要求激活软件，要我输入激活码#

答：只需要将这个Unable to Save Data Error saving license data.C:\Users\HAOYANG\AppData\Roaming\JetBrains\IntelliJIdea2024.3\idea.key(拒绝访问。) 关闭IDEA后，把提示路径下的idea.key删掉，重新激活就可以了。

10.IDEA每次打开总是要求激活软件，要我输入激活码#

答：使用过本站提供的激活到 2025/2026 年版本脚本，需要执行对应卸载脚本，将自动添加的环境变量删除。

d2b5ca33bd20250110145422

11.出现 Error occurred during initialization of VM agent library failed Agent_OnLoad: instrumentPlease try to reinstall the IDE. For support, please refer to https://jb.gg/ide/critical-startup-errors 解决方法#

img

问题原因：#

路径不全，JVM 找不到对应的 jar 包，无法执行程序，这导致了 VM 报错。

鹏星尝试弄出这种错误，按照网上说法是：这段代码在C:\Users\Lenovo\AppData\Roaming\JetBrains\IntelliJIdea2024.3文件夹下，创建的idea64.exe.vmoptions还包含-javaagent。删除掉-javaagent保存下就可以打开了

鹏星个人尝试把JetBrains同级文件夹InteIIiJIdea删除同样会出现该问题，如果InteIIiJIdea无法找回，那么可以把JetBrains文件里面的IntelliJIdea2024.3文件夹删除，这个时候就相当于我们电脑第一次安装IDEA

img

12.（免费版本的插件激活时功能有限。要解锁全部功能，请升级到高级版本。）A free version of the plugin is activated with limited featuresTo unlock full functionality, upgrade to the premium version.#

img

昨天小编也是第一次亲眼看到，IDEA安装会出现这样的错误，经历多番尝试，最终还是解决了这个问题。

多次测试后发现是新用户在第一次安装JetBarins产品，区域选择默认的中国大陆选区

解决办法#

按住快捷键 windos + R, 然后输入 regedit 回车调出注册表。

依次点击菜单 计算机\HKEY_CURRENT_USER\SOFTWARE\JavaSoft\Prefs\jetbrains，然后右键删除。

img

残留清理#

最后，还有几个地方的缓存数据需要删除：

1
C:\用户\${用户名称}\IdeaProjects\
2
# 如果你想删除 IDEA 相关，则只需要删除 JetBrains 目录下包含 IDEA 的文件夹即可
3
C:\用户\${用户名称}\AppData\Roaming\JetBrains
4
# 如果你想删除 IDEA 相关，则只需要删除 JetBrains 目录下包含 IDEA 的文件夹即可
5
C:\用户\${用户名称}\AppData\Local\JetBrains
6
C:\用户\公用\.jetbrains
7
# 如果你想删除 IDEA 相关，则只需要删除 JetBrains 目录下包含 IDEA 的文件夹即可
8
C:\Program Files\JetBrains
9
C:\ProgramData\Microsoft\Windows\Start Menu\Programs\JetBrains\

MAC电脑删除干净#

打开【访达】-> 【应用程序】, 找到 IDEA 右键【移到废纸篓】：

img

残留清理#

打开终端，执行如下命令，进入 Library 目录下，准备删除 IDEA 的残留信息：

注意：路径中的 XXX 为用户名，替换成你实际的用户名，再执行即可。

1
cd /Users/XXX/Library

新老版本残留所在的目录不一样#

建议先 cd 进去看下文件夹命名规则，再删除。

较新版本#

执行如下删除命令：

TIP: * 表示版本号。

1
rm -rf Preferences/JetBrains/IntelliJIdea*
2
rm -rf Caches/JetBrains/IntelliJIdea*
3
rm -rf Application\ Support/JetBrains/IntelliJIdea*
4
rm -rf Logs/JetBrains/IntelliJIdea*

老版本#

执行如下删除命令：

1
rm -rf Preferences/IntelliJIdea*
2
rm -rf Caches/IntelliJIdea*
3
rm -rf Application\ Support/IntelliJIdea*
4
rm -rf Logs/IntelliJIdea*

三、总结#

总的来说我们遇到的错误大多数都是来自电脑没有完全卸载JetBrains产品，对于新用户来说，激活文件有概率会被杀毒软件给屏蔽掉，还有人喜欢直接在压缩包中操作，这些情况都是不会成功的。

网站又被攻击了(宕机)

Mon, 17 Nov 2025 00:00:00 GMT

前言#

早在年初时，我通过wordpress搭建了一个博客，当时这个博客主要用来分享软件，其中浏览量最高的是IntelliJ IDEA和PyCharm软件安装的相关教程。因为服务器采用的是2核2G的阿里云服务器，所以这个博客不能支持“大量”用户同时访问，不过一天的访问量也有几百人，有时候会出现访问超时，或者访问失败的情况。用户来源基本上是通过B站了解到的，但是我的B站视频被人举报下架，还连同我的账号被封禁了。看着每日腰斩的访问量，我也就索性把网站给关闭了。

现在#

我也是最近才想起来我特么还有一个服务器，虽然日常吃灰状态，但是想起来了还是用用吧。

于是重新部署一遍word press，毕竟是轻车熟路，弄这玩意简直是毫无压力啊，博客前端还是继续采用子比主题，自从弄了这个博客以后，我一共就写了两篇文章，并且都是IntelliJ IDEA的激活教程，然后就TM的跟见鬼似的，一个月只有1300的访问量还有人会压测我这个网站，我特么也是服了，还特么作死访问后台，一直想要看数据库，我特么也是佩服你这个人才！

首先我后面新建的这个博客都已经禁止所有用户注册了，所有除了我这个管理员账号还会有谁在啊，其次一共才两篇文章，这特么还不明显吗，我没有复原上一次的数据啊，现在的这个网站和空壳没有一点区别。最后我这个网站就重来没有要求过用户需要关注公众号，让你去公众号中获取资源，网盘链接和文字版激活教程都TM直接是一起的，只要打开文章一看就能获取所有东西了，并且你只要把文章复制下来，还特么是一篇markdown格式文档，你特么保存后想怎么看就怎么看，所以我是真的没有想明白弄我这个网站的意义在哪，搞得我后面不得对每一个请求做一个限制。

限制同一时间同一个IP多次访问请求的配置展开收起

1
user  www www;
2
worker_processes auto;
3
error_log  /www/wwwlogs/nginx_error.log  crit;
4
pid        /www/server/nginx/logs/nginx.pid;
5
worker_rlimit_nofile 51200;
6

7
stream {
8
    log_format tcp_format '$time_local|$remote_addr|$protocol|$status|$bytes_sent|$bytes_received|$session_time|$upstream_addr|$upstream_bytes_sent|$upstream_bytes_received|$upstream_connect_time';
9

10
    access_log /www/wwwlogs/tcp-access.log tcp_format;
11
    error_log /www/wwwlogs/tcp-error.log;
12
    include /www/server/panel/vhost/nginx/tcp/*.conf;
13
}
14

15
events {
16
    use epoll;
17
    worker_connections 51200;
18
    multi_accept on;
19
}
20

21
http {
22
    # 创建一个共享内存区域用于存储访问频率信息
23
    limit_req_zone $binary_remote_addr zone=one:10m rate=2r/s;
24
    limit_conn_zone $binary_remote_addr zone=perip:10m;
25
    limit_conn_zone $server_name zone=perserver:10m;
26

27
    include       mime.types;
28
    include proxy.conf;
29
    lua_package_path "/www/server/nginx/lib/lua/?.lua;;";
30

31
    default_type  application/octet-stream;
32

33
    server_names_hash_bucket_size 512;
34
    client_header_buffer_size 32k;
35
    large_client_header_buffers 4 32k;
36
    client_max_body_size 50m;
37

38
    sendfile   on;
39
    tcp_nopush on;
40

41
    keepalive_timeout 60;
42

43
    tcp_nodelay on;
44

45
    fastcgi_connect_timeout 300;
46
    fastcgi_send_timeout 300;
47
    fastcgi_read_timeout 300;
48
    fastcgi_buffer_size 64k;
49
    fastcgi_buffers 4 64k;
50
    fastcgi_busy_buffers_size 128k;
51
    fastcgi_temp_file_write_size 256k;
52
    fastcgi_intercept_errors on;
53

54
    gzip on;
55
    gzip_min_length  1k;
56
    gzip_buffers     4 16k;
57
    gzip_http_version 1.1;
58
    gzip_comp_level 5;
59
    gzip_types     text/plain application/javascript application/x-javascript text/javascript text/css application/xml application/json image/jpeg image/gif image/png font/ttf font/otf image/svg+xml application/xml+rss text/x-js;
60
    gzip_vary on;
61
    gzip_proxied   expired no-cache no-store private auth;
62
    gzip_disable   "MSIE [1-6]\.";
63

64
    server_tokens off;
65
    access_log off;
66

67
    server {
68
        listen 888;
69
        server_name phpmyadmin;
70
        index index.html index.htm index.php;
71
        root  /www/server/phpmyadmin;
72

73
        #error_page   404   /404.html;
74
        include enable-php.conf;
75

76
        location ~ .*\.(gif|jpg|jpeg|png|bmp|swf)$ {
77
            expires      30d;
78
        }
79

80
        location ~ .*\.(js|css)?$ {
81
            expires      12h;
82
        }
83

84
        location ~ /\.
85
        {
86
            deny all;
87
        }
88

89
        # 应用限制
90
        location / {
91
            limit_req zone=one burst=5 nodelay;
92
            limit_conn perip 10;
93
            limit_conn perserver 100;
94
        }
95

96
        access_log  /www/wwwlogs/access.log;
97
    }
98

99
    include /www/server/panel/vhost/nginx/*.conf;
100
}

展开收起

自从弄这个限制后，我也就没管了，不过网站也安静了一个月，直到今天，我在访问网站时出现了建立数据库连接时出错看了一下宝塔面板给出的异常运行日志，

异常运行日志

1
2025/11/15 20:47:50 [error] 1048855#0: *253594 directory index of ＂/www/wwwroot/lzphy.top/wp-admin/css/colors/light/＂ is forbidden, client: 4.197.170.217, server: lzphy.top, request: ＂GET /wp-admin/css/colors/light/ HTTP/1.1＂, host: ＂lzphy.top＂
2
2025/11/15 20:47:50 [error] 1048855#0: *253594 directory index of ＂/www/wwwroot/lzphy.top/wp-includes/certificates/＂ is forbidden, client: 4.197.170.217, server: lzphy.top, request: ＂GET /wp-includes/certificates/ HTTP/1.1＂, host: ＂lzphy.top＂
3
2025/11/15 20:48:01 [error] 1048855#0: *253594 directory index of ＂/www/wwwroot/lzphy.top/wp-includes/block-supports/＂ is forbidden, client: 4.197.170.217, server: lzphy.top, request: ＂GET /wp-includes/block-supports/ HTTP/1.1＂, host: ＂lzphy.top＂
4
2025/11/15 20:48:03 [error] 1048855#0: *253594 directory index of ＂/www/wwwroot/lzphy.top/wp-content/upgrade/＂ is forbidden, client: 4.197.170.217, server: lzphy.top, request: ＂GET /wp-content/upgrade/ HTTP/1.1＂, host: ＂lzphy.top＂

所以我觉得换为静态博客非常非常不错，反正我的博客也不需要用户登录注册，cloudflare每天10万访问量完全是搓搓有余，tnnd我还不需要当心其他东西。

音乐播放器配置

Mon, 10 Nov 2025 00:00:00 GMT

概述#

音乐播放器配置用于在网站中添加音乐播放功能，基于 APlayer 和 MetingJS，支持本地音乐和在线音乐两种模式。

基础配置#

启用音乐播放器#

1
export const musicPlayerConfig: MusicPlayerConfig = {
2
  enable: true, // 启用音乐播放器功能
3
  mode: "local", // 播放器模式："local" 本地音乐，"meting" 在线音乐
4
};

播放器模式#

本地音乐模式#

1
local: {
2
  playlist: [
3
    {
4
      name: "歌曲名称",
5
      artist: "艺术家",
6
      url: "/assets/music/song.wav", // 音乐文件路径
7
      cover: "/assets/music/cover/cover.jpg", // 封面图片路径（可选）
8
      lrc: "", // 歌词内容，支持 LRC 格式（可选）
9
    },
10
  ],
11
}

本地音乐文件要求：

音乐文件放在 public/assets/music/ 目录下
封面图片放在 public/assets/music/cover/ 目录下
支持格式：MP3、WAV、OGG、M4A等
路径使用相对于 public 目录的路径（以 / 开头）

在线音乐模式（Meting API）#

1
meting: {
2
  // Meting API 地址
3
  api: "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
4

5
  // 音乐平台：netease=网易云音乐, tencent=QQ音乐, kugou=酷狗音乐, xiami=虾米音乐, baidu=百度音乐
6
  server: "netease",
7

8
  // 类型：song=单曲, playlist=歌单, album=专辑, search=搜索, artist=艺术家
9
  type: "playlist",
10

11
  // 歌单/专辑/单曲 ID 或搜索关键词
12
  id: "8814137515", // 网易云音乐歌单ID示例
13

14
  // 认证 token（可选）
15
  auth: "",
16

17
  // 备用 API 配置（当主 API 失败时使用）
18
  fallbackApis: [
19
    "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
20
  ],
21

22
  // MetingJS 脚本路径
23
  // 默认使用 CDN：https://cdn.jsdelivr.net/npm/meting@2/dist/Meting.min.js
24
  // 备用CDN：https://unpkg.com/meting@2/dist/Meting.min.js
25
  // 也可配置为本地路径（支持非根目录部署）
26
  jsPath: "https://unpkg.com/meting@2/dist/Meting.min.js",
27
}

展开收起

支持的音乐平台：

netease: 网易云音乐
tencent: QQ音乐
kugou: 酷狗音乐
xiami: 虾米音乐
baidu: 百度音乐

类型选项：

playlist: 歌单
album: 专辑
song: 单曲
search: 搜索
artist: 艺术家

MetingJS 脚本路径说明：

支持 CDN 路径（http:// 或 https:// 开头）
支持本地路径（以 / 开头，会自动处理非根目录部署问题）
如果不配置，默认使用 https://cdn.jsdelivr.net/npm/meting@2/dist/Meting.min.js

APlayer 配置选项#

1
player: {
2
  // 是否自动播放（浏览器可能会阻止，需用户交互一次网页后才自动播放）
3
  autoplay: true,
4

5
  // 主题色
6
  theme: "var(--btn-regular-bg)", // 可以使用 CSS 变量或颜色值
7

8
  // 循环模式：'all'=列表循环, 'one'=单曲循环, 'none'=不循环
9
  loop: "all",
10

11
  // 播放顺序：'list'=列表顺序, 'random'=随机播放
12
  order: "list",
13

14
  // 预加载：'none'=不预加载, 'metadata'=预加载元数据, 'auto'=自动
15
  preload: "auto",
16

17
  // 默认音量 (0-1)
18
  volume: 0.7,
19

20
  // 是否互斥播放（同时只能播放一个播放器）
21
  mutex: true,
22

23
  // 歌词类型：0=不显示, 1=显示（需要提供 lrc 字段）, 2=显示（从 HTML 内容读取）, 3=异步加载（从 API 获取）
24
  lrcType: 3,
25

26
  // 歌词是否默认隐藏（当 lrcType 不为 0 时，可以通过此选项控制初始显示状态）
27
  // true=默认隐藏（用户可以通过歌词按钮手动显示）, false=默认显示
28
  lrcHidden: true,
29

30
  // 播放列表是否默认折叠
31
  listFolded: false,
32

33
  // 播放列表最大高度
34
  listMaxHeight: "340px",
35

36
  // localStorage 存储键名
37
  storageName: "aplayer-setting",
38
}

展开收起

播放器固定位置和迷你模式说明：

fixed 和 mini 默认为 true，无需在配置中设置
播放器固定在页面右下角（fixed 模式）
默认以迷你模式显示（mini 模式）
如果需要修改这些行为，需要修改组件源码

自动播放说明：

现代浏览器通常会阻止自动播放音频
配置 autoplay: true 后，播放器会在用户第一次交互（点击、滚动、按键等）后自动开始播放
这是浏览器安全策略的要求，无法绕过

歌词配置说明：

lrcType: 0 - 不显示歌词
lrcType: 1 - 显示歌词（需要在本地音乐的 lrc 字段中提供歌词内容）
lrcType: 2 - 从 HTML 内容读取歌词（用于单个本地音乐）
lrcType: 3 - 异步加载歌词（用于 Meting API，从 API 获取歌词）
lrcHidden - 当歌词功能启用时，控制初始显示状态

响应式配置#

1
responsive: {
2
  mobile: {
3
    // 在移动端是否隐藏
4
    hide: false,
5

6
    // 移动端断点（小于此宽度时应用移动端配置）
7
    breakpoint: 768, // 单位：px
8
  },
9
}

使用示例#

完整配置示例（本地音乐）#

1
export const musicPlayerConfig: MusicPlayerConfig = {
2
  enable: true,
3
  mode: "local",
4

5
  local: {
6
    playlist: [
7
      {
8
        name: "使一颗心免于哀伤",
9
        artist: "知更鸟 / HOYO-MiX / Chevy",
10
        url: "/assets/music/使一颗心免于哀伤-哼唱.wav",
11
        cover: "/assets/music/cover/109951169585655912.jpg",
12
        lrc: "", // 歌词内容，支持 LRC 格式
13
      },
14
    ],
15
  },
16

17
  player: {
18
    autoplay: true,
19
    theme: "var(--btn-regular-bg)",
20
    loop: "all",
21
    order: "list",
22
    preload: "auto",
23
    volume: 0.7,
24
    mutex: true,
25
    lrcType: 3,
26
    lrcHidden: true,
27
    listFolded: false,
28
    listMaxHeight: "340px",
29
    storageName: "aplayer-setting",
30
  },
31

32
  responsive: {
33
    mobile: {
34
      hide: false,
35
      breakpoint: 768,
36
    },
37
  },
38
};

展开收起

完整配置示例（Meting API）#

1
export const musicPlayerConfig: MusicPlayerConfig = {
2
  enable: true,
3
  mode: "meting",
4

5
  meting: {
6
    api: "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
7
    server: "netease",
8
    type: "playlist",
9
    id: "8814137515",
10
    auth: "",
11
    fallbackApis: [
12
      "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
13
    ],
14
    jsPath: "https://unpkg.com/meting@2/dist/Meting.min.js",
15
  },
16

17
  player: {
18
    autoplay: true,
19
    theme: "var(--btn-regular-bg)",
20
    loop: "all",
21
    order: "list",
22
    preload: "auto",
23
    volume: 0.7,
24
    mutex: true,
25
    lrcType: 3, // Meting API 模式下使用 3 从 API 获取歌词
26
    lrcHidden: false, // 默认显示歌词
27
    listFolded: false,
28
    listMaxHeight: "340px",
29
    storageName: "aplayer-setting",
30
  },
31

32
  responsive: {
33
    mobile: {
34
      hide: false,
35
      breakpoint: 768,
36
    },
37
  },
38
};

展开收起

单个本地音乐配置示例（使用 MetingJS）#

当本地音乐列表只有一首歌曲时，会自动使用 MetingJS 渲染：

1
local: {
2
  playlist: [
3
    {
4
      name: "歌曲名称",
5
      artist: "艺术家",
6
      url: "/assets/music/song.wav",
7
      cover: "/assets/music/cover/cover.jpg",
8
      lrc: "[00:00.00] 歌词内容...", // 歌词内容，lrcType 会使用 2
9
    },
10
  ],
11
}

多个本地音乐配置示例（使用 APlayer 直接初始化）#

当本地音乐列表有多首歌曲时，会使用 APlayer 直接初始化：

1
local: {
2
  playlist: [
3
    {
4
      name: "歌曲1",
5
      artist: "艺术家1",
6
      url: "/assets/music/song1.wav",
7
      cover: "/assets/music/cover/cover1.jpg",
8
      lrc: "", // 多个音乐时，lrcType 使用配置的值
9
    },
10
    {
11
      name: "歌曲2",
12
      artist: "艺术家2",
13
      url: "/assets/music/song2.wav",
14
      cover: "/assets/music/cover/cover2.jpg",
15
      lrc: "",
16
    },
17
  ],
18
}

展开收起

实现代码#

复制music文件#

夸克网盘：https://pan.quark.cn/s/c9afe5235080

image-20251110203601122

新建 musicConfig.ts 文件#

如果没有把 src/config.ts 模块化，那么不需要新建 musicConfig.ts 文件，直接把 musicPlayerConfig 写入到 config.ts 中就行

musicConfig.ts展开收起

1
import type { MusicPlayerConfig } from "../types/config";
2

3
// 音乐播放器配置
4
export const musicPlayerConfig: MusicPlayerConfig = {
5
  // 基础功能开关
6
  enable: true, // 启用音乐播放器功能
7

8
  // 使用方式：'meting' 或 'local'
9
  mode: "meting", // "meting" 使用 Meting API，"local" 使用本地音乐列表
10

11
  // Meting API 配置
12
  meting: {
13
    // Meting API 地址
14
    // 默认使用官方 API，也可以使用自定义 API
15
    api: "https://api.i-meto.com/meting/api?server=:server&type=:type&id=:id&r=:r",
16

17
    // 音乐平台：netease=网易云音乐, tencent=QQ音乐, kugou=酷狗音乐, xiami=虾米音乐, baidu=百度音乐
18
    server: "netease",
19

20
    // 类型：song=单曲, playlist=歌单, album=专辑, search=搜索, artist=艺术家
21
    type: "playlist",
22

23
    // 歌单/专辑/单曲 ID 或搜索关键词
24
    id: "10046455237", // 网易云音乐歌单ID示例
25

26
    // 认证 token（可选）
27
    auth: "",
28

29
    // 备用 API 配置（当主 API 失败时使用）
30
    fallbackApis: [
31
      "https://api.injahow.cn/meting/?server=:server&type=:type&id=:id",
32
      "https://api.moeyao.cn/meting/?server=:server&type=:type&id=:id",
33
    ],
34

35
    // MetingJS 脚本路径
36
    // 默认使用 CDN：https://cdn.jsdelivr.net/npm/meting@2/dist/Meting.min.js
37
    // 备用CDN：https://unpkg.com/meting@2/dist/Meting.min.js
38
    // 也可配置为本地路径
39
    jsPath: "https://unpkg.com/meting@2/dist/Meting.min.js",
40
  },
41

42
  // 本地音乐配置（当 mode 为 'local' 时使用）
43
  local: {
44
    playlist: [
45
      {
46
        name: "使一颗心免于哀伤",
47
        artist: "知更鸟 / HOYO-MiX / Chevy",
48
        url: "/assets/music/使一颗心免于哀伤-哼唱.wav",
49
        cover: "/assets/music/cover/109951169585655912.jpg",
50
        lrc: "", // 歌词内容，支持 LRC 格式
51
      },
52
    ],
53
  },
54

55
  // APlayer 配置选项
56
  player: {
57
    // 是否自动播放  浏览器可能会阻止，需用户交互一次网页后才自动播放
58
    autoplay: false,
59

60
    // 主题色
61
    theme: "var(--btn-regular-bg)",
62

63
    // 循环模式：'all'=列表循环, 'one'=单曲循环, 'none'=不循环
64
    loop: "all",
65

66
    // 播放顺序：'list'=列表顺序, 'random'=随机播放
67
    order: "list",
68

69
    // 预加载：'none'=不预加载, 'metadata'=预加载元数据, 'auto'=自动
70
    preload: "auto",
71

72
    // 默认音量 (0-1)
73
    volume: 0.7,
74

75
    // 是否互斥播放（同时只能播放一个播放器）
76
    mutex: true,
77

78
    // 歌词类型：0=不显示, 1=显示（需要提供 lrc 字段）, 2=显示（从 HTML 内容读取）, 3=异步加载（从 API 获取）
79
    lrcType: 3,
80

81
    // 歌词是否默认隐藏（当 lrcType 不为 0 时，可以通过此选项控制初始显示状态）
82
    // true=默认隐藏（用户可以通过歌词按钮手动显示）, false=默认显示
83
    lrcHidden: true,
84

85
    // 播放列表是否默认折叠
86
    listFolded: false,
87

88
    // 播放列表最大高度
89
    listMaxHeight: "340px",
90

91
    // localStorage 存储键名
92
    storageName: "aplayer-setting",
93
  },
94

95
  // 响应式配置
96
  responsive: {
97
    // 移动端配置
98
    mobile: {
99
      // 在移动端是否隐藏
100
      hide: false,
101

102
      // 移动端断点（小于此宽度时应用移动端配置）
103
      breakpoint: 768,
104
    },
105
  },
106
};

展开收起

新增src\types\config.ts音乐类别#

src\types\config.ts展开收起

1
// 。。。。省略
2

3
// 音乐播放器配置
4
export type MusicPlayerConfig = {
5
  // 基础功能开关
6
  enable: boolean; // 启用音乐播放器功能
7

8
  // 使用方式：'meting' 或 'local'
9
  mode?: "meting" | "local"; // "meting" 使用 Meting API，"local" 使用本地音乐列表
10

11
  // Meting API 配置
12
  meting?: {
13
    // Meting API 地址
14
    api?: string;
15

16
    // 音乐平台：netease=网易云音乐, tencent=QQ音乐, kugou=酷狗音乐, xiami=虾米音乐, baidu=百度音乐
17
    server?: "netease" | "tencent" | "kugou" | "xiami" | "baidu";
18

19
    // 类型：song=单曲, playlist=歌单, album=专辑, search=搜索, artist=艺术家
20
    type?: "song" | "playlist" | "album" | "search" | "artist";
21

22
    // 歌单/专辑/单曲 ID 或搜索关键词
23
    id?: string;
24

25
    // 认证 token（可选）
26
    auth?: string;
27

28
    // 备用 API 配置（当主 API 失败时使用）
29
    fallbackApis?: string[];
30

31
    // MetingJS 脚本路径（默认使用 CDN，也可配置为本地路径）
32
    jsPath?: string;
33
  };
34

35
  // 本地音乐配置（当 mode 为 'local' 时使用）
36
  local?: {
37
    playlist?: Array<{
38
      name: string; // 歌曲名称
39
      artist: string; // 艺术家
40
      url: string; // 音乐文件路径（相对于 public 目录）
41
      cover?: string; // 封面图片路径（相对于 public 目录）
42
      lrc?: string; // 歌词内容，支持 LRC 格式
43
    }>;
44
  };
45

46
  // APlayer 配置选项
47
  player?: {
48
    // 是否固定模式（固定在页面底部）
49
    fixed?: boolean;
50

51
    // 是否迷你模式
52
    mini?: boolean;
53

54
    // 是否自动播放
55
    autoplay?: boolean;
56

57
    // 主题色
58
    theme?: string;
59

60
    // 循环模式：'all'=列表循环, 'one'=单曲循环, 'none'=不循环
61
    loop?: "all" | "one" | "none";
62

63
    // 播放顺序：'list'=列表顺序, 'random'=随机播放
64
    order?: "list" | "random";
65

66
    // 预加载：'none'=不预加载, 'metadata'=预加载元数据, 'auto'=自动
67
    preload?: "none" | "metadata" | "auto";
68

69
    // 默认音量 (0-1)
70
    volume?: number;
71

72
    // 是否互斥播放（同时只能播放一个播放器）
73
    mutex?: boolean;
74

75
    // 歌词类型：0=不显示, 1=显示（需要提供 lrc 字段）, 2=显示（从 HTML 内容读取）, 3=异步加载（从 API 获取）
76
    lrcType?: 0 | 1 | 2 | 3;
77

78
    // 歌词是否默认隐藏（当 lrcType 不为 0 时，可以通过此选项控制初始显示状态）
79
    lrcHidden?: boolean;
80

81
    // 播放列表是否默认折叠
82
    listFolded?: boolean;
83

84
    // 播放列表最大高度
85
    listMaxHeight?: string;
86

87
    // localStorage 存储键名
88
    storageName?: string;
89
  };
90

91
  // 响应式配置
92
  responsive?: {
93
    // 移动端配置
94
    mobile?: {
95
      // 在移动端是否隐藏
96
      hide?: boolean;
97

98
      // 移动端断点（小于此宽度时应用移动端配置）
99
      breakpoint?: number;
100
    };
101
  };
102
};

展开收起

新增src\components\widget\MusicPlayer.astro组件#

src\components\widget\MusicPlayer.astro展开收起

1
---
2
import { musicPlayerConfig } from "@/config/musicConfig";
3
import { url } from "@/utils/url-utils";
4

5
const config = musicPlayerConfig;
6

7
// 预先生成本地资源路径，确保在非根目录部署时也能正确加载
8
const aplayerCssPath = url("/assets/css/APlayer.min.css");
9
const aplayerCustomCssPath = url("/assets/css/APlayer.custom.css");
10
const aplayerJsPath = url("/assets/js/APlayer.min.js");
11

12
// MetingJS 路径处理
13
// 如果配置的是相对路径（以 / 开头），使用 url() 处理以确保非根目录部署时正确
14
// 如果是完整的 URL（http/https），直接使用
15
const metingJsPath = config.meting?.jsPath
16
  ? config.meting.jsPath.startsWith("http://") ||
17
    config.meting.jsPath.startsWith("https://")
18
    ? config.meting.jsPath
19
    : url(config.meting.jsPath)
20
  : "https://cdn.jsdelivr.net/npm/meting@2/dist/Meting.min.js"; // 默认 CDN 路径
21

22
// 预处理本地音乐列表的路径（如果使用本地模式）
23
const processedLocalPlaylist =
24
  config.mode === "local" && config.local?.playlist
25
    ? config.local.playlist.map((song) => ({
26
        ...song,
27
        url: url(song.url),
28
        cover: song.cover ? url(song.cover) : undefined,
29
      }))
30
    : null;
31
---
32

33
{config.enable && (
34
  <>
35
    <!-- APlayer CSS -->
36
    <link
37
      rel="stylesheet"
38
      href={aplayerCssPath}
39
    />
40
    <link
41
      rel="stylesheet"
42
      href={aplayerCustomCssPath}
43
    />
44

45
    <!-- 音乐播放器容器 -->
46
    <div
47
      id="aplayer-container"
48
      class:mobile-hide={config.responsive?.mobile?.hide}
49
    >
50
      {config.mode === "meting" && config.meting ? (
51
        <!-- 使用 MetingJS -->
52
        <meting-js
53
          server={config.meting.server || "netease"}
54
          type={config.meting.type || "playlist"}
55
          id={config.meting.id || ""}
56
          api={config.meting.api}
57
          auth={config.meting.auth}
58
          fixed={(config.player?.fixed ?? true) ? "true" : "false"}
59
          mini={(config.player?.mini ?? true) ? "true" : "false"}
60
          autoplay={config.player?.autoplay ? "true" : "false"}
61
          theme={config.player?.theme || "#b7daff"}
62
          loop={config.player?.loop || "all"}
63
          order={config.player?.order || "list"}
64
          preload={config.player?.preload || "auto"}
65
          volume={String(config.player?.volume ?? 0.7)}
66
          mutex={config.player?.mutex !== false ? "true" : "false"}
67
          lrc-type={String(config.player?.lrcType ?? 3)}
68
          list-folded={config.player?.listFolded ? "true" : "false"}
69
          list-max-height={config.player?.listMaxHeight || "340px"}
70
          storage-name={config.player?.storageName || "aplayer-setting"}
71
        />
72
      ) : config.mode === "local" && processedLocalPlaylist && processedLocalPlaylist.length > 0 ? (
73
        <!-- 使用本地音乐列表 -->
74
        <!-- 单个音乐使用 MetingJS，多个音乐使用 APlayer 直接初始化 -->
75
        {processedLocalPlaylist.length === 1 ? (
76
          <meting-js
77
            name={processedLocalPlaylist?.[0]?.name || ""}
78
            artist={processedLocalPlaylist?.[0]?.artist || ""}
79
            url={processedLocalPlaylist?.[0]?.url || ""}
80
            cover={processedLocalPlaylist?.[0]?.cover}
81
            fixed={(config.player?.fixed ?? true) ? "true" : "false"}
82
            mini={(config.player?.mini ?? true) ? "true" : "false"}
83
            autoplay={config.player?.autoplay ? "true" : "false"}
84
            theme={config.player?.theme || "#b7daff"}
85
            loop={config.player?.loop || "all"}
86
            order={config.player?.order || "list"}
87
            preload={config.player?.preload || "auto"}
88
            volume={String(config.player?.volume ?? 0.7)}
89
            mutex={config.player?.mutex !== false ? "true" : "false"}
90
            lrc-type={processedLocalPlaylist[0]?.lrc ? "2" : "0"}
91
            list-folded={config.player?.listFolded ? "true" : "false"}
92
            list-max-height={config.player?.listMaxHeight || "340px"}
93
            storage-name={config.player?.storageName || "aplayer-setting"}
94
          >
95
            {processedLocalPlaylist?.[0]?.lrc && (
96
              <pre hidden>
97
                {processedLocalPlaylist[0].lrc}
98
              </pre>
99
            )}
100
          </meting-js>
101
        ) : (
102
          <!-- 多个本地音乐，使用 APlayer 直接初始化 -->
103
          <div id="local-aplayer"></div>
104
        )}
105
      ) : null}
106
    </div>
107
  </>
108
)}
109

110
<script define:vars={{ config, aplayerJsPath, metingJsPath, processedLocalPlaylist }} is:inline>
111
  // 动态加载 APlayer 和 MetingJS
112
  (function() {
113
    if (!config.enable) return;
114

115
    // 确保在浏览器环境中运行
116
    if (typeof window === 'undefined') return;
117

118
    // 加载 APlayer JS
119
    function loadAPlayer() {
120
      return new Promise((resolve) => {
121
        if (window.APlayer) {
122
          resolve(window.APlayer);
123
          return;
124
        }
125

126
        const aplayerScript = document.createElement("script");
127
        aplayerScript.src = aplayerJsPath;
128
        aplayerScript.async = true;
129
        aplayerScript.onload = () => resolve(window.APlayer);
130
        aplayerScript.onerror = () => {
131
          console.error("Failed to load APlayer");
132
          resolve(null);
133
        };
134
        document.head.appendChild(aplayerScript);
135
      });
136
    }
137

138
    // 全局用户交互状态
139
    if (!window.hasMusicInteracted) {
140
      window.hasMusicInteracted = false;
141
    }
142

143
    function tryAutoplay(aplayer) {
144
      if (!config.player?.autoplay) return;
145

146
      // 如果用户已经交互过，立即尝试播放
147
      if (window.hasMusicInteracted) {
148
        if (aplayer && aplayer.paused) {
149
          const playPromise = aplayer.play();
150
          if (playPromise && typeof playPromise.catch === 'function') {
151
            playPromise.catch((error) => {
152
              // 浏览器阻止自动播放是正常的，不需要报错
153
              if (error.name !== 'NotAllowedError') {
154
                console.log('自动播放失败:', error.name);
155
              }
156
            });
157
          }
158
        }
159
      } else {
160
        // 等待用户第一次交互后自动播放
161
        const enableAutoplay = () => {
162
          if (window.hasMusicInteracted) return;
163
          window.hasMusicInteracted = true;
164

165
          if (aplayer && aplayer.paused) {
166
            const playPromise = aplayer.play();
167
            if (playPromise && typeof playPromise.catch === 'function') {
168
              playPromise.catch((error) => {
169
                if (error.name !== 'NotAllowedError') {
170
                  console.log('自动播放失败:', error.name);
171
                }
172
              });
173
            }
174
          }
175
        };
176

177
        // 监听各种用户交互事件（只监听一次）
178
        ['click', 'keydown', 'touchstart', 'scroll'].forEach(eventType => {
179
          document.addEventListener(eventType, enableAutoplay, {
180
            once: true,
181
            passive: true
182
          });
183
        });
184
      }
185
    }
186

187
    // 检查 MetingJS 元素是否成功加载了音乐
188
    function checkMetingSuccess(metingElement, timeout = 5000) {
189
      return new Promise((resolve) => {
190
        const startTime = Date.now();
191

192
        const checkSuccess = setInterval(() => {
193
          const aplayer = metingElement?.aplayer;
194
          // 检查是否有 APlayer 实例且有音频列表
195
          if (aplayer && aplayer.list && aplayer.list.audios && aplayer.list.audios.length > 0) {
196
            clearInterval(checkSuccess);
197
            resolve(true);
198
            return;
199
          }
200

201
          // 超时检查
202
          if (Date.now() - startTime >= timeout) {
203
            clearInterval(checkSuccess);
204
            resolve(false);
205
          }
206
        }, 100);
207
      });
208
    }
209

210
    // 重新创建 MetingJS 元素以使用新的 API
211
    function recreateMetingElement(container, apiUrl, config) {
212
      // 移除旧的元素
213
      const oldElement = container.querySelector('meting-js');
214
      if (oldElement) {
215
        // 如果已有 APlayer 实例，先销毁它
216
        if (oldElement.aplayer) {
217
          try {
218
            oldElement.aplayer.destroy();
219
          } catch (e) {
220
            console.warn('销毁旧 APlayer 实例时出错:', e);
221
          }
222
        }
223
        oldElement.remove();
224
      }
225

226
      // 创建新元素
227
      const newElement = document.createElement('meting-js');
228
      newElement.setAttribute('server', config.meting?.server || 'netease');
229
      newElement.setAttribute('type', config.meting?.type || 'playlist');
230
      newElement.setAttribute('id', config.meting?.id || '');
231
      newElement.setAttribute('api', apiUrl);
232
      if (config.meting?.auth) {
233
        newElement.setAttribute('auth', config.meting.auth);
234
      }
235
      newElement.setAttribute('fixed', (config.player?.fixed ?? true) ? 'true' : 'false');
236
      newElement.setAttribute('mini', (config.player?.mini ?? true) ? 'true' : 'false');
237
      newElement.setAttribute('autoplay', config.player?.autoplay ? 'true' : 'false');
238
      newElement.setAttribute('theme', config.player?.theme || '#b7daff');
239
      newElement.setAttribute('loop', config.player?.loop || 'all');
240
      newElement.setAttribute('order', config.player?.order || 'list');
241
      newElement.setAttribute('preload', config.player?.preload || 'auto');
242
      newElement.setAttribute('volume', String(config.player?.volume ?? 0.7));
243
      newElement.setAttribute('mutex', config.player?.mutex !== false ? 'true' : 'false');
244
      newElement.setAttribute('lrc-type', String(config.player?.lrcType ?? 3));
245
      newElement.setAttribute('list-folded', config.player?.listFolded ? 'true' : 'false');
246
      newElement.setAttribute('list-max-height', config.player?.listMaxHeight || '340px');
247
      newElement.setAttribute('storage-name', config.player?.storageName || 'aplayer-setting');
248

249
      container.appendChild(newElement);
250
      return newElement;
251
    }
252

253
    // 处理移动端显示/隐藏
254
    function handleMobileVisibility(aplayer) {
255
      if (!aplayer || !aplayer.container) return;
256

257
      const shouldHide = config.responsive?.mobile?.hide === true;
258
      const breakpoint = config.responsive?.mobile?.breakpoint || 768;
259
      const isMobile = window.innerWidth <= breakpoint;
260

261
      if (shouldHide && isMobile) {
262
        aplayer.container.style.display = 'none';
263
        aplayer.container.classList.add('mobile-hide');
264

265
        // 同时处理容器（如果存在）
266
        const container = document.getElementById('aplayer-container');
267
        if (container) {
268
          container.style.display = 'none';
269
          container.classList.add('mobile-hide');
270
        }
271
      } else {
272
        aplayer.container.style.display = '';
273
        aplayer.container.classList.remove('mobile-hide');
274

275
        // 同时处理容器（如果存在）
276
        const container = document.getElementById('aplayer-container');
277
        if (container) {
278
          container.style.display = '';
279
          container.classList.remove('mobile-hide');
280
        }
281
      }
282
    }
283

284
    // 初始化时处理容器的移动端显示/隐藏
285
    function initContainerMobileVisibility() {
286
      const container = document.getElementById('aplayer-container');
287
      if (!container) return;
288

289
      const shouldHide = config.responsive?.mobile?.hide === true;
290
      const breakpoint = config.responsive?.mobile?.breakpoint || 768;
291
      const isMobile = window.innerWidth <= breakpoint;
292

293
      if (shouldHide && isMobile) {
294
        container.style.display = 'none';
295
        container.classList.add('mobile-hide');
296
      } else {
297
        container.style.display = '';
298
        container.classList.remove('mobile-hide');
299
      }
300

301
      // 监听窗口大小变化
302
      const resizeHandler = () => {
303
        const nowIsMobile = window.innerWidth <= breakpoint;
304
        if (shouldHide && nowIsMobile) {
305
          container.style.display = 'none';
306
          container.classList.add('mobile-hide');
307
        } else {
308
          container.style.display = '';
309
          container.classList.remove('mobile-hide');
310
        }
311
      };
312
      window.addEventListener('resize', resizeHandler);
313
    }
314

315
    // 初始化 MetingJS 元素并设置播放器
316
    function setupMetingElement(metingElement) {
317
      return new Promise((resolve) => {
318
        // 监听 aplayer 初始化
319
        const checkAPlayer = setInterval(() => {
320
          const aplayer = metingElement.aplayer;
321
          if (aplayer && aplayer.container) {
322
            clearInterval(checkAPlayer);
323

324
            // 监听播放状态，更新封面动画
325
            const updatePlayingState = () => {
326
              if (aplayer.container) {
327
                const isPlaying = !aplayer.paused;
328
                aplayer.container.setAttribute('data-playing', String(isPlaying));
329
                if (isPlaying) {
330
                  aplayer.container.classList.add('aplayer-playing');
331
                } else {
332
                  aplayer.container.classList.remove('aplayer-playing');
333
                }
334
              }
335
            };
336

337
            // 监听播放/暂停事件
338
            if (aplayer.audio) {
339
              aplayer.audio.addEventListener('play', updatePlayingState);
340
              aplayer.audio.addEventListener('pause', updatePlayingState);
341
              aplayer.audio.addEventListener('ended', updatePlayingState);
342
            }
343

344
            aplayer.container.setAttribute('data-positioned', 'right');
345
            // 立即应用右侧样式
346
            requestAnimationFrame(() => {
347
              if (aplayer.container) {
348
                aplayer.container.style.right = '0';
349
                aplayer.container.style.left = 'unset';
350

351
                // 初始化播放状态
352
                updatePlayingState();
353

354
                // 处理移动端显示/隐藏
355
                handleMobileVisibility(aplayer);
356

357
                // 监听窗口大小变化，动态调整显示/隐藏
358
                const resizeHandler = () => handleMobileVisibility(aplayer);
359
                window.addEventListener('resize', resizeHandler);
360

361
                // 短暂延迟后标记为已初始化，恢复展开动画
362
                setTimeout(() => {
363
                  aplayer.container.setAttribute('data-initialized', 'true');
364

365
                  // 如果配置了默认隐藏歌词，则隐藏歌词
366
                  if (config.player?.lrcHidden && aplayer.lrc) {
367
                    aplayer.lrc.hide();
368
                    // 同时设置歌词按钮为未激活状态
369
                    const lrcButton = aplayer.container.querySelector('.aplayer-icon-lrc');
370
                    if (lrcButton) {
371
                      lrcButton.classList.add('aplayer-icon-lrc-inactivity');
372
                    }
373
                  }
374

375
                  // 如果自动播放被阻止，等待用户交互后恢复
376
                  if (config.player?.autoplay && aplayer.paused) {
377
                    tryAutoplay(aplayer);
378
                  }
379
                }, 200);
380
              }
381
            });
382

383
            resolve(true);
384
          }
385
        }, 50);
386

387
        // 10秒后停止检查
388
        setTimeout(() => {
389
          clearInterval(checkAPlayer);
390
          resolve(false);
391
        }, 10000);
392
      });
393
    }
394

395
    // 使用备用 API 重试加载
396
    async function retryWithFallbackAPI(container, fallbackApis, currentIndex = 0) {
397
      if (currentIndex >= fallbackApis.length) {
398
        console.error('所有 API 都失败了，无法加载音乐播放器');
399
        return null;
400
      }
401

402
      const fallbackApi = fallbackApis[currentIndex];
403
      console.log(`尝试使用备用 API ${currentIndex + 1}/${fallbackApis.length}: ${fallbackApi}`);
404

405
      // 替换 API URL 中的占位符
406
      const server = config.meting?.server || 'netease';
407
      const type = config.meting?.type || 'playlist';
408
      const id = config.meting?.id || '';
409

410
      let apiUrl = fallbackApi
411
        .replace(':server', server)
412
        .replace(':type', type)
413
        .replace(':id', id);
414

415
      // 设置全局 API
416
      window.meting_api = apiUrl;
417

418
      // 重新创建元素
419
      const newElement = recreateMetingElement(container, apiUrl, config);
420

421
      // 等待元素初始化
422
      await new Promise(resolve => setTimeout(resolve, 500));
423

424
      // 检查是否成功
425
      const success = await checkMetingSuccess(newElement, 5000);
426

427
      if (success) {
428
        console.log(`备用 API ${currentIndex + 1} 成功加载音乐`);
429
        return newElement;
430
      } else {
431
        // 如果失败，尝试下一个备用 API
432
        return retryWithFallbackAPI(container, fallbackApis, currentIndex + 1);
433
      }
434
    }
435

436
    // 加载 MetingJS
437
    function loadMetingJS() {
438
      return new Promise((resolve) => {
439
        if (window.customElements?.get("meting-js")) {
440
          resolve(true);
441
          return;
442
        }
443

444
        const metingScript = document.createElement("script");
445
        metingScript.src = metingJsPath;
446
        metingScript.async = true;
447
        metingScript.onload = async () => {
448
          // 等待 MetingJS 元素创建
449
          await new Promise(resolve => setTimeout(resolve, 100));
450

451
          const container = document.getElementById('aplayer-container');
452
          if (!container) {
453
            resolve(false);
454
            return;
455
          }
456

457
          let metingElement = container.querySelector('meting-js');
458

459
          if (config.mode === "meting" && config.meting?.api && metingElement) {
460
            const server = config.meting.server || 'netease';
461
            const type = config.meting.type || 'playlist';
462
            const id = config.meting.id || '';
463

464
            // 替换 API URL 中的占位符
465
            let mainApiUrl = config.meting.api
466
              .replace(':server', server)
467
              .replace(':type', type)
468
              .replace(':id', id)
469
              .replace(':r', Math.random().toString());
470

471
            // 设置全局 API
472
            window.meting_api = mainApiUrl;
473

474
            console.log('尝试使用主 API:', mainApiUrl);
475

476
            // 等待元素初始化
477
            await new Promise(resolve => setTimeout(resolve, 500));
478

479
            // 检查主 API 是否成功
480
            const mainApiSuccess = await checkMetingSuccess(metingElement, 5000);
481

482
            if (!mainApiSuccess && config.meting.fallbackApis && config.meting.fallbackApis.length > 0) {
483
              // 主 API 失败，尝试备用 API
484
              console.warn('主 API 失败，尝试使用备用 API');
485
              const newElement = await retryWithFallbackAPI(container, config.meting.fallbackApis);
486
              if (newElement) {
487
                metingElement = newElement;
488
              }
489
            }
490
          }
491

492
          // 设置播放器（如果元素存在）
493
          if (metingElement) {
494
            await setupMetingElement(metingElement);
495
          }
496

497
          resolve(true);
498
        };
499
        metingScript.onerror = () => {
500
          console.error("Failed to load MetingJS");
501
          resolve(false);
502
        };
503
        document.head.appendChild(metingScript);
504
      });
505
    }
506

507
    // 初始化本地音乐播放器（多个音乐）
508
    async function initLocalPlayer() {
509
      if (
510
        config.mode !== "local" ||
511
        !processedLocalPlaylist ||
512
        processedLocalPlaylist.length <= 1
513
      ) {
514
        return;
515
      }
516

517
      const APlayerClass = await loadAPlayer();
518
      if (!APlayerClass) return;
519

520
      const container = document.getElementById("local-aplayer");
521
      if (!container) return;
522

523
      // 使用预处理好的路径列表（已经在服务端处理了非根目录部署的问题）
524
      const audioList = processedLocalPlaylist.map((song) => ({
525
        name: song.name,
526
        artist: song.artist,
527
        url: song.url,
528
        cover: song.cover,
529
        lrc: song.lrc || undefined,
530
        type: "auto",
531
      }));
532

533
      const aplayerOptions = {
534
        container: container,
535
        audio: audioList,
536
        mutex: config.player?.mutex !== false,
537
        lrcType: config.player?.lrcType !== undefined ? config.player.lrcType : 0,
538
        fixed: config.player?.fixed ?? true,
539
        mini: config.player?.mini ?? true,
540
        autoplay: config.player?.autoplay || false, // 直接设置 autoplay，浏览器可能会阻止但可以后续通过用户交互恢复
541
        theme: config.player?.theme || "#b7daff",
542
        loop: config.player?.loop || "all",
543
        order: config.player?.order || "list",
544
        preload: config.player?.preload || "auto",
545
        volume: config.player?.volume || 0.7,
546
        listFolded: config.player?.listFolded || false,
547
        listMaxHeight: config.player?.listMaxHeight || "340px",
548
        storageName: config.player?.storageName || "aplayer-setting",
549
      };
550

551
      try {
552
        const aplayer = new APlayerClass(aplayerOptions);
553

554
        // 监听播放状态，更新封面动画
555
        const updatePlayingState = () => {
556
          if (aplayer.container) {
557
            const isPlaying = !aplayer.paused;
558
            aplayer.container.setAttribute('data-playing', String(isPlaying));
559
            if (isPlaying) {
560
              aplayer.container.classList.add('aplayer-playing');
561
            } else {
562
              aplayer.container.classList.remove('aplayer-playing');
563
            }
564
          }
565
        };
566

567
        // 监听播放/暂停事件
568
        if (aplayer.audio) {
569
          aplayer.audio.addEventListener('play', updatePlayingState);
570
          aplayer.audio.addEventListener('pause', updatePlayingState);
571
          aplayer.audio.addEventListener('ended', updatePlayingState);
572
        }
573

574
              // 立即设置右侧定位，避免动画
575
              if (aplayer.container) {
576
                aplayer.container.setAttribute('data-positioned', 'right');
577
                // 确保立即应用右侧样式，避免从左到右的过渡
578
                requestAnimationFrame(() => {
579
                  if (aplayer.container) {
580
                    aplayer.container.style.right = '0';
581
                    aplayer.container.style.left = 'unset';
582

583
                    // 初始化播放状态
584
                    updatePlayingState();
585

586
                    // 处理移动端显示/隐藏
587
                    handleMobileVisibility(aplayer);
588

589
                    // 监听窗口大小变化，动态调整显示/隐藏
590
                    const resizeHandler = () => handleMobileVisibility(aplayer);
591
                    window.addEventListener('resize', resizeHandler);
592

593
                    // 短暂延迟后标记为已初始化，恢复展开动画
594
                    setTimeout(() => {
595
                      aplayer.container.setAttribute('data-initialized', 'true');
596

597
                      // 如果配置了默认隐藏歌词，则隐藏歌词
598
                      if (config.player?.lrcHidden && aplayer.lrc) {
599
                        aplayer.lrc.hide();
600
                        // 同时设置歌词按钮为未激活状态
601
                        const lrcButton = aplayer.container.querySelector('.aplayer-icon-lrc');
602
                        if (lrcButton) {
603
                          lrcButton.classList.add('aplayer-icon-lrc-inactivity');
604
                        }
605
                      }
606

607
                      // 如果自动播放被阻止，等待用户交互后恢复
608
                      if (config.player?.autoplay && aplayer.paused) {
609
                        tryAutoplay(aplayer);
610
                      }
611
                    }, 100);
612
                  }
613
                });
614
              }
615
      } catch (error) {
616
        console.error("Failed to initialize APlayer:", error);
617
      }
618
    }
619

620
    // 初始化容器的移动端显示/隐藏
621
    if (document.readyState === "loading") {
622
      document.addEventListener("DOMContentLoaded", initContainerMobileVisibility);
623
    } else {
624
      initContainerMobileVisibility();
625
    }
626

627
    // 如果使用 Meting 模式，加载 MetingJS
628
    if (config.mode === "meting") {
629
      loadAPlayer().then(() => {
630
        loadMetingJS();
631
      });
632
    } else if (config.mode === "local") {
633
      // 本地模式：单个音乐使用 MetingJS，多个音乐使用 APlayer
634
      if (processedLocalPlaylist && processedLocalPlaylist.length > 1) {
635
        // 多个音乐，使用 APlayer
636
        if (document.readyState === "loading") {
637
          document.addEventListener("DOMContentLoaded", initLocalPlayer);
638
        } else {
639
          initLocalPlayer();
640
        }
641
      } else {
642
        // 单个音乐，使用 MetingJS
643
        loadAPlayer().then(() => {
644
          loadMetingJS();
645
        });
646
      }
647
    }
648
  })();
649
</script>
650

651
<style>
652
  #aplayer-container {
653
    position: relative;
654
    z-index: 1000;
655
  }
656

657
  /* 确保播放器在固定模式下正确显示 */
658
  #aplayer-container .aplayer-fixed {
659
    z-index: 9999;
660
  }
661

662
  /* 禁用 APlayer 初始化时的过渡动画，避免收缩效果 */
663
  #aplayer-container .aplayer.aplayer-fixed {
664
    animation: none !important;
665
  }
666

667
  #aplayer-container .aplayer.aplayer-fixed .aplayer-body {
668
    animation: none !important;
669
    transition: none !important;
670
  }
671

672
  /* 确保播放器初始化时就在右侧位置 */
673
  #aplayer-container .aplayer.aplayer-fixed[data-positioned="right"] {
674
    right: 0 !important;
675
    left: unset !important;
676
  }
677

678
  /* 移动端隐藏 - 通过 JavaScript 动态添加类 */
679
  .aplayer-fixed.mobile-hide {
680
    display: none !important;
681
  }
682

683
  /* 移动端隐藏容器 */
684
  #aplayer-container.mobile-hide {
685
    display: none !important;
686
  }
687
</style>

展开收起

修改src\layouts\Layout.astro组件#

src\layouts\Layout.astro展开收起

1
---
2
import "@fontsource/roboto/400.css";
3
import "@fontsource/roboto/500.css";
4
import "@fontsource/roboto/700.css";
5

6
import ConfigCarrier from "@components/ConfigCarrier.astro";
7
import MusicPlayer from "@components/widget/MusicPlayer.astro";
8
import SakuraEffect from "@/components/effects/SakuraEffect.astro";
9
import { profileConfig, siteConfig } from "@/config";
10

11
---
12

13
<!DOCTYPE html>
14
<html lang={siteLang} class="bg-[var(--page-bg)] transition text-[14px] md:text-[16px]"
15
    data-overlayscrollbars-initialize
16
>
17
  <head>
18

19
    //。。。。省略
20

21
  </head>
22
  <body class=" min-h-screen transition " class:list={[{"lg:is-home": isHomePage, "enable-banner": enableBanner}]}
23
      data-overlayscrollbars-initialize
24
  >
25
    <ConfigCarrier></ConfigCarrier>
26
    <slot />
27

28
    <!-- Music Player -->
29
    <MusicPlayer />
30
    <!-- 樱花特效 -->
31
    <SakuraEffect/>
32
    <!-- increase the page height during page transition to prevent the scrolling animation from jumping -->
33
    <div id="page-height-extend" class="hidden h-[300vh]"></div>
34
  </body>
35
</html>
36

37
// 。。。。省略

展开收起

路径处理说明#

音乐播放器组件会自动处理非根目录部署的路径问题：

本地音乐文件的 url 和 cover 路径会自动使用 url() 工具函数处理
MetingJS 脚本路径如果配置为本地路径（以 / 开头），也会自动处理
CDN 路径（http:// 或 https:// 开头）不会进行任何处理，直接使用

注意事项#

浏览器限制：现代浏览器通常阻止自动播放，即使设置了 autoplay: true，也需要用户交互一次后才会自动播放
文件格式：确保音乐文件格式被浏览器支持（MP3、WAV、OGG、M4A等）
文件大小：注意音乐文件大小，过大的文件会影响加载速度
版权问题：使用在线音乐时请注意版权问题
API稳定性：在线音乐API可能不稳定，建议配置多个备用API
固定位置：播放器默认固定在右下角，fixed 和 mini 默认均为 true，无法通过配置文件修改
歌词显示：Meting API 模式下，歌词需要 API 返回歌词数据才能显示；本地音乐模式下，需要提供 lrc 字段内容
路径配置：本地音乐文件的路径必须相对于 public 目录，以 / 开头

常见问题#

Q: 音乐无法播放怎么办？

A: 检查文件路径是否正确，确保音乐文件格式被浏览器支持，文件路径以 / 开头

Q: 如何添加更多歌曲？

A: 在 local.playlist 数组中添加更多歌曲对象

Q: 如何更换音乐平台？

A: 修改 meting.server 的值（netease、tencent、kugou等）

Q: 自动播放不生效怎么办？

A: 这是正常的浏览器安全策略，需要用户交互一次后才会自动播放。如果页面加载后立即需要播放，需要用户先点击页面任意位置

Q: 如何隐藏歌词？

A: 设置 player.lrcHidden: true，或设置 player.lrcType: 0 完全禁用歌词功能

Q: 如何获取网易云音乐歌单ID？

A: 在网易云音乐网页版打开歌单，URL 中的数字就是歌单ID，例如：https://music.163.com/#/playlist?id=8814137515 中的 8814137515

Q: 如何在非根目录部署时使用本地 MetingJS 脚本？

A: 将 MetingJS 脚本文件放在 public/assets/js/ 目录下，然后在配置中设置 meting.jsPath: "/assets/js/Meting.min.js"，组件会自动处理路径问题

Q: 歌词不显示怎么办？

Meting API 模式：检查 lrcType 是否为 3，并确认 API 返回了歌词数据
本地音乐模式：检查是否提供了 lrc 字段内容，并设置正确的 lrcType（单个音乐使用 2，多个音乐使用 1）

Q: 播放器位置可以调整吗？

A: 播放器固定在右下角，位置无法通过配置文件调整。如需调整，需要修改组件源码中的 CSS 样式

看板娘配置

Sun, 09 Nov 2025 00:00:00 GMT

概述#

pioConfig.ts 文件用于配置网站中的看板娘功能，支持 Spine 和 Live2D 两种类型的看板娘模型。

配置类型#

1. Spine 看板娘配置#

Spine 是一种2D骨骼动画技术，适合制作轻量级的看板娘动画。

基本配置结构#

1
interface SpineModelConfig {
2
  enable: boolean;                    // 是否启用
3
  model: {
4
    path: string;                    // 模型文件路径
5
    scale: number;                   // 缩放比例
6
    x: number;                       // X轴偏移
7
    y: number;                       // Y轴偏移
8
  };
9
  position: {
10
    corner: string;                  // 显示位置
11
    offsetX: number;                 // X轴偏移
12
    offsetY: number;                 // Y轴偏移
13
  };
14
  size: {
15
    width: number;                   // 容器宽度
16
    height: number;                  // 容器高度
17
  };
18
  interactive: {
19
    enabled: boolean;                // 是否启用交互
20
    clickAnimations: string[];       // 点击动画列表
21
    clickMessages: string[];         // 点击消息列表
22
    messageDisplayTime: number;      // 消息显示时间
23
    idleAnimations: string[];        // 待机动画列表
24
    idleInterval: number;            // 待机动画间隔
25
  };
26
  responsive: {
27
    hideOnMobile: boolean;           // 移动端是否隐藏
28
    mobileBreakpoint: number;        // 移动端断点
29
  };
30
  zIndex: number;                    // 层级
31
  opacity: number;                   // 透明度
32
}

展开收起

配置示例#

1
export const spineModelConfig: SpineModelConfig = {
2
  enable: true,
3
  model: {
4
    path: "/pio/models/spine/firefly/1310.json",
5
    scale: 1.0,
6
    x: 0,
7
    y: 0,
8
  },
9
  position: {
10
    corner: "bottom-left",
11
    offsetX: 0,
12
    offsetY: 0,
13
  },
14
  size: {
15
    width: 250,
16
    height: 280,
17
  },
18
  interactive: {
19
    enabled: true,
20
    clickAnimations: [
21
      "emoji_0", "emoji_1", "emoji_2",
22
      "emoji_3", "emoji_4", "emoji_5", "emoji_6"
23
    ],
24
    clickMessages: [
25
      "你好呀！我是流萤~",
26
      "今天也要加油哦！✨",
27
      "想要一起去看星空吗？🌟"
28
    ],
29
    messageDisplayTime: 3000,
30
    idleAnimations: ["idle", "emoji_0", "emoji_1"],
31
    idleInterval: 8000,
32
  },
33
  responsive: {
34
    hideOnMobile: true,
35
    mobileBreakpoint: 768,
36
  },
37
  zIndex: 1000,
38
  opacity: 1.0,
39
};

展开收起

2. Live2D 看板娘配置#

Live2D 是一种更高级的2D角色动画技术，提供更丰富的表情和动作。

基本配置结构#

1
interface Live2DModelConfig {
2
  enable: boolean;                    // 是否启用
3
  model: {
4
    path: string;                    // 模型文件路径
5
  };
6
  position: {
7
    corner: string;                  // 显示位置
8
    offsetX: number;                 // X轴偏移
9
    offsetY: number;                 // Y轴偏移
10
  };
11
  size: {
12
    width: number;                   // 容器宽度
13
    height: number;                  // 容器高度
14
  };
15
  interactive: {
16
    enabled: boolean;                // 是否启用交互
17
    clickMessages: string[];         // 点击消息列表
18
    messageDisplayTime: number;      // 消息显示时间
19
  };
20
  responsive: {
21
    hideOnMobile: boolean;           // 移动端是否隐藏
22
    mobileBreakpoint: number;        // 移动端断点
23
  };
24
}

展开收起

配置示例#

1
export const live2dModelConfig: Live2DModelConfig = {
2
  enable: false,
3
  model: {
4
    path: "/pio/models/live2d/snow_miku/model.json",
5
  },
6
  position: {
7
    corner: "bottom-right",
8
    offsetX: 0,
9
    offsetY: 0,
10
  },
11
  size: {
12
    width: 230,
13
    height: 280,
14
  },
15
  interactive: {
16
    enabled: true,
17
    clickMessages: [
18
      "你好！我是Miku~",
19
      "有什么需要帮助的吗？",
20
      "今天天气真不错呢！"
21
    ],
22
    messageDisplayTime: 3000,
23
  },
24
  responsive: {
25
    hideOnMobile: true,
26
    mobileBreakpoint: 768,
27
  },
28
};

展开收起

配置选项详解#

位置配置 (position)#

显示位置 (corner)#

值	说明
`"bottom-left"`	左下角
`"bottom-right"`	右下角
`"top-left"`	左上角
`"top-right"`	右上角

偏移设置#

1
position: {
2
  corner: "bottom-right",
3
  offsetX: 20,  // 距离右边缘20px
4
  offsetY: 20,  // 距离底部20px
5
}

尺寸配置 (size)#

1
size: {
2
  width: 250,   // 容器宽度（像素）
3
  height: 280,  // 容器高度（像素）
4
}

注意事项：

尺寸过大会影响页面性能
建议根据模型实际大小调整
移动端会自动缩放

交互配置 (interactive)#

点击动画 (clickAnimations)#

1
clickAnimations: [
2
  "emoji_0",    // 动画名称1
3
  "emoji_1",    // 动画名称2
4
  "emoji_2"     // 动画名称3
5
]

说明：

动画名称必须与模型文件中的动画名称一致
点击时会随机播放其中一个动画
可以添加多个动画增加趣味性

点击消息 (clickMessages)#

1
clickMessages: [
2
  "你好呀！我是流萤~",
3
  "今天也要加油哦！✨",
4
  "想要一起去看星空吗？🌟"
5
]

说明：

点击时会随机显示一条消息
支持emoji表情
消息会显示在模型旁边

待机动画 (idleAnimations)#

1
idleAnimations: [
2
  "idle",      // 基础待机动画
3
  "emoji_0",   // 其他待机动画
4
  "emoji_1"
5
]

说明：

模型空闲时会循环播放这些动画
建议包含一个基础的idle动画
可以添加多个动画增加变化

响应式配置 (responsive)#

1
responsive: {
2
  hideOnMobile: true,        // 移动端隐藏
3
  mobileBreakpoint: 768,     // 移动端断点（像素）
4
}

断点说明：

屏幕宽度小于断点值时视为移动端
移动端可以隐藏看板娘以节省空间
建议断点设置为768px

模型文件管理#

文件结构#

文件结构

1
public/pio/models/
2
├── spine/                    # Spine模型目录
3
│   └── haoyang/             # 具体模型目录
4
│       ├── 1310.json        # 模型配置文件
5
│       ├── 1310.atlas       # 图集文件
6
│       └── 1310.png         # 纹理图片
7
└── live2d/                  # Live2D模型目录
8
    └── snow_miku/           # 具体模型目录
9
        ├── model.json       # 模型配置文件
10
        └── textures/        # 纹理目录
11
            └── *.png        # 纹理图片

模型文件获取#

Spine 模型#

从官方商店购买或下载免费模型
导出为JSON格式
确保包含.atlas和.png文件

Live2D 模型#

从官方商店购买或下载免费模型
确保包含model.json文件
整理纹理文件到textures目录

实现代码#

复制看板娘文件#

夸克网盘：https://pan.quark.cn/s/c9afe5235080

image-20251109185059499

新建 pioConfig.ts 文件#

如果没有把 src/config.ts 模块化，那么不需要新建 pioConfig.ts 文件，直接把 spineModelConfig 或live2dModelConfig 写入到 config.ts 中就行

Spine 看板娘配置和 Live2D 看板娘配置展开收起

1
import type { SpineModelConfig, Live2DModelConfig } from "../types/config";
2

3
// Spine 看板娘配置
4
export const spineModelConfig: SpineModelConfig = {
5
  enable: true, // 启用 Spine 看板娘
6
  model: {
7
    // Spine模型文件路径
8
    path: "/pio/models/spine/haoyang/1310.json",
9
    scale: 1.0, // 模型缩放比例
10
    x: 0, // X轴偏移
11
    y: 0, // Y轴偏移
12
  },
13
  position: {
14
    // 显示位置 bottom-left，bottom-right，top-left，top-right，注意：在右下角可能会挡住返回顶部按钮
15
    corner: "bottom-left",
16
    offsetX: 0, // 距离右边缘0px
17
    offsetY: 0, // 距离底部0px
18
  },
19
  size: {
20
    width: 135, // 容器宽度
21
    height: 165, // 容器高度
22
  },
23
  interactive: {
24
    enabled: true, // 启用交互功能
25
    clickAnimations: [
26
      "emoji_0",
27
      "emoji_1",
28
      "emoji_2",
29
      "emoji_3",
30
      "emoji_4",
31
      "emoji_5",
32
      "emoji_6",
33
    ], // 点击时随机播放的动画列表
34
    clickMessages: [
35
      "你好呀！我是鹏星~",
36
      "今天也要加油哦！✨",
37
      "想要一起去看星空吗？🌟",
38
      "记得要好好休息呢~",
39
      "有什么想对我说的吗？💫",
40
      "让我们一起探索未知的世界吧！🚀",
41
      "每一颗星星都有自己的故事~⭐",
42
      "希望能带给你温暖和快乐！💖",
43
    ], // 点击时随机显示的文字消息
44
    messageDisplayTime: 3000, // 文字显示时间（毫秒）
45
    idleAnimations: ["idle", "emoji_0", "emoji_1", "emoji_3", "emoji_4"], // 待机动画列表
46
    idleInterval: 8000, // 待机动画切换间隔（8秒）
47
  },
48
  responsive: {
49
    hideOnMobile: true, // 在移动端隐藏
50
    mobileBreakpoint: 768, // 移动端断点
51
  },
52
  zIndex: 1000, // 层级
53
  opacity: 1.0, // 完全不透明
54
};
55

56
// Live2D 看板娘配置
57
export const live2dModelConfig: Live2DModelConfig = {
58
  enable: false, // 启用 Live2D 看板娘
59
  model: {
60
    // Live2D模型文件路径
61
    path: "/pio/models/live2d/snow_miku/model.json",
62
    // path: "/pio/models/live2d/illyasviel/illyasviel.model.json",
63
  },
64
  position: {
65
    // 显示位置 bottom-left，bottom-right，top-left，top-right，注意：在右下角可能会挡住返回顶部按钮
66
    corner: "bottom-left", // 显示位置
67
    offsetX: 0, // 距离边缘20px
68
    offsetY: 0, // 距离底部20px
69
  },
70
  size: {
71
    width: 135, // 容器宽度
72
    height: 165, // 容器高度
73
  },
74
  interactive: {
75
    enabled: true, // 启用交互功能
76
    // motions 和 expressions 将从模型 JSON 文件中自动读取
77
    clickMessages: [
78
      "你好！我是鹏星~",
79
      "有什么需要帮助的吗？",
80
      "今天天气真不错呢！",
81
      "要不要一起玩游戏？",
82
      "记得按时休息哦！",
83
    ], // 点击时随机显示的文字消息
84
    messageDisplayTime: 3000, // 文字显示时间（毫秒）
85
  },
86
  responsive: {
87
    hideOnMobile: true, // 在移动端隐藏
88
    mobileBreakpoint: 768, // 移动端断点
89
  },
90
};

展开收起

新增src\types\config.ts看板娘类别#

Spine 看板娘配置和Live2D 看板娘配置展开收起

1
// Spine 看板娘配置
2
export type SpineModelConfig = {
3
  enable: boolean; // 是否启用 Spine 看板娘
4
  model: {
5
    path: string; // 模型文件路径 (.json)
6
    scale?: number; // 模型缩放比例，默认1.0
7
    x?: number; // X轴偏移，默认0
8
    y?: number; // Y轴偏移，默认0
9
  };
10
  position: {
11
    corner: "bottom-left" | "bottom-right" | "top-left" | "top-right"; // 显示位置
12
    offsetX?: number; // 水平偏移量，默认20px
13
    offsetY?: number; // 垂直偏移量，默认20px
14
  };
15
  size: {
16
    width?: number; // 容器宽度，默认280px
17
    height?: number; // 容器高度，默认400px
18
  };
19
  interactive?: {
20
    enabled?: boolean; // 是否启用交互功能，默认true
21
    clickAnimations?: string[]; // 点击时随机播放的动画列表
22
    clickMessages?: string[]; // 点击时随机显示的文字消息
23
    messageDisplayTime?: number; // 文字显示时间（毫秒），默认3000
24
    idleAnimations?: string[]; // 待机动画列表
25
    idleInterval?: number; // 待机动画切换间隔（毫秒），默认10000
26
  };
27
  responsive?: {
28
    hideOnMobile?: boolean; // 是否在移动端隐藏，默认false
29
    mobileBreakpoint?: number; // 移动端断点，默认768px
30
  };
31
  zIndex?: number; // 层级，默认1000
32
  opacity?: number; // 透明度，0-1，默认1.0
33
  };
34

35
  // Live2D 看板娘配置
36
  export type Live2DModelConfig = {
37
  enable: boolean; // 是否启用 Live2D 看板娘
38
  model: {
39
    path: string; // 模型文件夹路径或model3.json文件路径
40
  };
41
  position?: {
42
    corner?: "bottom-left" | "bottom-right" | "top-left" | "top-right"; // 显示位置，默认bottom-right
43
    offsetX?: number; // 水平偏移量，默认20px
44
    offsetY?: number; // 垂直偏移量，默认20px
45
  };
46
  size?: {
47
    width?: number; // 容器宽度，默认280px
48
    height?: number; // 容器高度，默认250px
49
  };
50
  interactive?: {
51
    enabled?: boolean; // 是否启用交互功能，默认true
52
    // motions 和 expressions 将从模型 JSON 文件中自动读取
53
    clickMessages?: string[]; // 点击时随机显示的文字消息
54
    messageDisplayTime?: number; // 文字显示时间（毫秒），默认3000
55
  };
56
  responsive?: {
57
    hideOnMobile?: boolean; // 是否在移动端隐藏，默认false
58
    mobileBreakpoint?: number; // 移动端断点，默认768px
59
  };
60
  };

展开收起

新建src\components\widget\PioMessageBox.astro#

src\components\widget\PioMessageBox.astro展开收起

1
---
2
// 消息框公共组件
3
// 用于Live2D和Spine模型的消息显示
4
---
5

6
<script>
7
    // 全局变量，跟踪当前显示的消息容器和隐藏定时器
8
    let currentMessageContainer: HTMLDivElement | null = null;
9
    let hideMessageTimer: number | null = null;
10

11
    // 消息显示函数
12
    export function showMessage(message: string, options: { containerId?: string; displayTime?: number } = {}) {
13
      // 防止空消息或重复调用
14
      if (!message || !message.trim()) {
15
        return;
16
      }
17

18
      // 立即清除之前的消息
19
      if (currentMessageContainer) {
20
        if (hideMessageTimer !== null) {
21
          clearTimeout(hideMessageTimer);
22
        }
23
        if (currentMessageContainer.parentNode) {
24
          currentMessageContainer.parentNode.removeChild(currentMessageContainer);
25
        }
26
        currentMessageContainer = null;
27
      }
28

29
      // 确保DOM中没有残留的消息容器
30
      const existingMessages = document.querySelectorAll(
31
        ".model-message-container"
32
      );
33
      existingMessages.forEach((msg) => {
34
        if (msg.parentNode) {
35
          msg.parentNode.removeChild(msg);
36
        }
37
      });
38

39
      // 检测暗色主题
40
      const isDarkMode =
41
        document.documentElement.classList.contains("dark") ||
42
        window.matchMedia("(prefers-color-scheme: dark)").matches;
43

44
      // 创建消息容器
45
      const messageContainer = document.createElement("div");
46
      messageContainer.className = "model-message-container";
47

48
      // 创建消息元素
49
      const messageEl = document.createElement("div");
50
      messageEl.className = "model-message";
51
      messageEl.textContent = message;
52

53
      // 创建箭头元素
54
      const arrowEl = document.createElement("div");
55
      arrowEl.className = "model-message-arrow";
56

57
      // 设置容器样式
58
      Object.assign(messageContainer.style, {
59
        position: "fixed",
60
        zIndex: "1001",
61
        pointerEvents: "none",
62
        opacity: "0",
63
        transform: "translateY(15px) translateX(-50%) scale(0.9)",
64
        transition: "all 0.4s cubic-bezier(0.34, 1.56, 0.64, 1)",
65
      });
66

67
      // 设置消息框美化样式（支持暗色主题）
68
      const messageStyles = {
69
        position: "relative",
70
        background: isDarkMode
71
          ? "linear-gradient(135deg, rgba(45, 55, 72, 0.95), rgba(26, 32, 44, 0.9))"
72
          : "linear-gradient(135deg, rgba(255, 255, 255, 0.95), rgba(240, 248, 255, 0.9))",
73
        color: isDarkMode ? "#e2e8f0" : "#2c3e50",
74
        padding: "12px 16px",
75
        borderRadius: "16px",
76
        fontSize: "14px",
77
        fontWeight: "500",
78
        fontFamily:
79
          '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
80
        maxWidth: "240px",
81
        minWidth: "100px",
82
        wordWrap: "break-word",
83
        textAlign: "center",
84
        whiteSpace: "pre-wrap",
85
        boxShadow: isDarkMode
86
          ? "0 8px 32px rgba(0, 0, 0, 0.3), 0 2px 8px rgba(0, 0, 0, 0.2)"
87
          : "0 8px 32px rgba(0, 0, 0, 0.12), 0 2px 8px rgba(0, 0, 0, 0.08)",
88
        border: isDarkMode
89
          ? "1px solid rgba(255, 255, 255, 0.1)"
90
          : "1px solid rgba(255, 255, 255, 0.6)",
91
        backdropFilter: "blur(12px)",
92
        letterSpacing: "0.3px",
93
        lineHeight: "1.4",
94
      };
95
      Object.assign(messageEl.style, messageStyles);
96

97
      // 设置箭头样式（居中显示）
98
      Object.assign(arrowEl.style, {
99
        position: "absolute",
100
        top: "100%",
101
        left: "50%",
102
        transform: "translateX(-50%)", // 箭头居中
103
        width: "0",
104
        height: "0",
105
        borderLeft: "8px solid transparent",
106
        borderRight: "8px solid transparent",
107
        borderTop: isDarkMode
108
          ? "8px solid rgba(45, 55, 72, 0.95)"
109
          : "8px solid rgba(255, 255, 255, 0.95)",
110
        filter: "drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1))",
111
      });
112

113
      // 组装消息框元素
114
      messageEl.appendChild(arrowEl);
115
      messageContainer.appendChild(messageEl);
116

117
      // 添加到页面并保存引用
118
      document.body.appendChild(messageContainer);
119
      currentMessageContainer = messageContainer;
120

121
      // 将消息显示在模型头顶居中
122
      const container = document.getElementById(options.containerId || "model-container");
123
      if (container) {
124
        const rect = container.getBoundingClientRect();
125

126
        // 消息框居中显示在模型上方
127
        const containerCenterX = rect.left + rect.width / 2;
128

129
        // 使用估算的消息框尺寸进行初步定位
130
        const estimatedMessageWidth = 240; // 使用maxWidth作为估算
131
        const estimatedMessageHeight = 60; // 估算高度
132
        const screenPadding = 10; // 距离屏幕边缘的最小距离
133

134
        // 计算消息框的实际位置（考虑translateX(-50%)的影响）
135
        let messageX = containerCenterX;
136
        let messageY = rect.top - estimatedMessageHeight - 25; // 距离模型顶部25px
137

138
        // 屏幕边界检查 - 水平方向
139
        const minX = screenPadding + estimatedMessageWidth / 2; // 考虑translateX(-50%)
140
        const maxX =
141
          window.innerWidth - screenPadding - estimatedMessageWidth / 2;
142

143
        if (messageX < minX) {
144
          messageX = minX;
145
        } else if (messageX > maxX) {
146
          messageX = maxX;
147
        }
148

149
        // 屏幕边界检查 - 垂直方向
150
        const minY = screenPadding;
151
        const maxY = window.innerHeight - estimatedMessageHeight - screenPadding;
152

153
        if (messageY < minY) {
154
          // 如果上方空间不够，显示在模型下方
155
          messageY = rect.bottom + 25;
156
          // 调整箭头方向（显示在下方）
157
          arrowEl.style.top = "0";
158
          arrowEl.style.bottom = "auto";
159
          arrowEl.style.borderTop = "none";
160
          arrowEl.style.borderBottom = isDarkMode
161
            ? "8px solid rgba(45, 55, 72, 0.95)"
162
            : "8px solid rgba(255, 255, 255, 0.95)";
163
        } else if (messageY > maxY) {
164
          messageY = maxY;
165
        }
166

167
        // 设置位置
168
        messageContainer.style.left = messageX + "px";
169
        messageContainer.style.top = messageY + "px";
170

171
        // 在消息框渲染后，进行精确的边界调整
172
        setTimeout(() => {
173
          const actualMessageRect = messageContainer.getBoundingClientRect();
174
          const actualWidth = actualMessageRect.width;
175
          const actualHeight = actualMessageRect.height;
176

177
          // 重新计算水平位置
178
          let adjustedX = containerCenterX;
179
          const actualMinX = screenPadding + actualWidth / 2;
180
          const actualMaxX = window.innerWidth - screenPadding - actualWidth / 2;
181

182
          if (adjustedX < actualMinX) {
183
            adjustedX = actualMinX;
184
          } else if (adjustedX > actualMaxX) {
185
            adjustedX = actualMaxX;
186
          }
187

188
          // 重新计算垂直位置
189
          let adjustedY = rect.top - actualHeight - 25;
190
          const actualMinY = screenPadding;
191
          const actualMaxY = window.innerHeight - actualHeight - screenPadding;
192
          let isAboveModel = true; // 标记消息框是否在模型上方
193

194
          if (adjustedY < actualMinY) {
195
            adjustedY = rect.bottom + 25;
196
            isAboveModel = false;
197
          } else if (adjustedY > actualMaxY) {
198
            adjustedY = actualMaxY;
199
          }
200

201
          // 计算箭头应该指向的位置（模型中心）
202
          const modelCenterX = rect.left + rect.width / 2;
203
          const messageCenterX = adjustedX; // 消息框中心位置
204
          const arrowOffsetX = modelCenterX - messageCenterX; // 箭头相对于消息框中心的偏移
205

206
          // 限制箭头偏移范围，避免超出消息框边界
207
          const maxOffset = actualWidth / 2 - 20; // 留出20px边距
208
          const clampedOffsetX = Math.max(
209
            -maxOffset,
210
            Math.min(maxOffset, arrowOffsetX)
211
          );
212

213
          // 根据最终位置调整箭头方向和位置
214
          if (isAboveModel) {
215
            // 消息框在模型上方，箭头向下
216
            Object.assign(arrowEl.style, {
217
              position: "absolute",
218
              top: "100%",
219
              left: "50%",
220
              bottom: "auto",
221
              transform: `translateX(calc(-50% + ${clampedOffsetX}px))`,
222
              width: "0",
223
              height: "0",
224
              borderLeft: "8px solid transparent",
225
              borderRight: "8px solid transparent",
226
              borderTop: isDarkMode
227
                ? "8px solid rgba(45, 55, 72, 0.95)"
228
                : "8px solid rgba(255, 255, 255, 0.95)",
229
              borderBottom: "none",
230
              filter: "drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1))",
231
            });
232
          } else {
233
            // 消息框在模型下方，箭头向上
234
            Object.assign(arrowEl.style, {
235
              position: "absolute",
236
              top: "0",
237
              left: "50%",
238
              bottom: "auto",
239
              transform: `translateX(calc(-50% + ${clampedOffsetX}px))`,
240
              width: "0",
241
              height: "0",
242
              borderLeft: "8px solid transparent",
243
              borderRight: "8px solid transparent",
244
              borderTop: "none",
245
              borderBottom: isDarkMode
246
                ? "8px solid rgba(45, 55, 72, 0.95)"
247
                : "8px solid rgba(255, 255, 255, 0.95)",
248
              filter: "drop-shadow(0 2px 4px rgba(0, 0, 0, 0.1))",
249
            });
250
          }
251

252
          // 应用调整后的位置
253
          messageContainer.style.left = adjustedX + "px";
254
          messageContainer.style.top = adjustedY + "px";
255
        }, 50); // 增加延迟确保消息框完全渲染
256
      }
257

258
      // 显示动画
259
      setTimeout(() => {
260
        messageContainer.style.opacity = "1";
261
        messageContainer.style.transform =
262
          "translateY(0) translateX(-50%) scale(1)";
263
      }, 100); // 延迟到边界调整完成后
264

265
      // 自动隐藏
266
      const displayTime = options.displayTime || 3000;
267
      hideMessageTimer = window.setTimeout(() => {
268
        messageContainer.style.opacity = "0";
269
        messageContainer.style.transform =
270
          "translateY(-15px) translateX(-50%) scale(0.95)";
271
        setTimeout(() => {
272
          if (messageContainer.parentNode) {
273
            messageContainer.parentNode.removeChild(messageContainer);
274
          }
275
          // 清除引用
276
          if (currentMessageContainer === messageContainer) {
277
            currentMessageContainer = null;
278
          }
279
        }, 400);
280
      }, displayTime);
281
    }
282

283
    // 清理消息函数
284
    export function clearMessage() {
285
      if (currentMessageContainer) {
286
        if (hideMessageTimer !== null) {
287
          clearTimeout(hideMessageTimer);
288
        }
289
        if (currentMessageContainer.parentNode) {
290
          currentMessageContainer.parentNode.removeChild(currentMessageContainer);
291
        }
292
        currentMessageContainer = null;
293
      }
294

295
      // 清理所有消息容器
296
      const existingMessages = document.querySelectorAll(
297
        ".model-message-container"
298
      );
299
      existingMessages.forEach((msg) => {
300
        if (msg.parentNode) {
301
          msg.parentNode.removeChild(msg);
302
        }
303
      });
304
    }
305

306
    // 将函数暴露到全局作用域
307
    (window as any).showModelMessage = showMessage;
308
    (window as any).clearModelMessage = clearMessage;
309
  </script>

展开收起

新建src\components\widget\Live2DWidget.astro#

src\components\widget\Live2DWidget.astro展开收起

1
---
2
import type { Live2DModelConfig } from "@/types/config";
3
import MessageBox from "./PioMessageBox.astro";
4
import { url } from "@/utils/url-utils";
5

6
interface Props {
7
  config: Live2DModelConfig;
8
}
9

10
const { config } = Astro.props;
11

12
// 获取位置和尺寸配置
13
const position = config.position || {
14
  corner: "bottom-right" as const,
15
  offsetX: 20,
16
  offsetY: 20,
17
};
18
const size = config.size || { width: 280, height: 250 };
19
---
20

21
<div
22
  id="live2d-widget"
23
  class="live2d-widget"
24
  style={`
25
    width: ${size.width}px;
26
    height: ${size.height}px;
27
    ${position.corner?.includes("right") ? "right" : "left"}: ${position.offsetX}px;
28
    ${position.corner?.includes("top") ? "top" : "bottom"}: ${position.offsetY}px;
29
  `}
30
>
31
  <canvas id="live2d-canvas" width={size.width} height={size.height}></canvas>
32
</div>
33

34
<!-- 引入消息框组件 -->
35
<MessageBox />
36

37
<script define:vars={{ config, modelPath: url(config.model.path), sdkPath: url("/pio/static/live2d-sdk/live2d.min.js") }}>
38
  let modelData = null;
39
  let motionGroups = {};
40
  let hitAreas = {};
41
  let currentMotionGroup = "idle";
42
  let currentMotionIndex = 0;
43

44
  // Use loadlive2d function from the working project
45
  function initLive2D() {
46
    if (!window.loadlive2d) {
47
      console.error("loadlive2d function not available");
48
      return;
49
    }
50

51
    if (!config.model || !config.model.path) {
52
      console.error("No model path configured");
53
      return;
54
    }
55

56
    const modelPath = modelPath;
57

58
    // Load model data first to get motion groups and hit areas
59
    fetch(modelPath)
60
      .then((response) => response.json())
61
      .then((data) => {
62
        modelData = data;
63
        motionGroups = data.motions || {};
64
        hitAreas = data.hit_areas_custom || data.hit_areas || {};
65

66
        console.log("Loaded model data:", {
67
          motionGroups: Object.keys(motionGroups),
68
          hitAreas: Object.keys(hitAreas),
69
        });
70

71
        // Load the model using loadlive2d
72
        window.loadlive2d("live2d-canvas", modelPath);
73

74
        // Setup interactions after a delay to ensure model is loaded
75
        setTimeout(() => {
76
          setupInteractions();
77
        }, 2000);
78
      })
79
      .catch((error) => {
80
        console.error("Failed to load model data:", error);
81
      });
82
  }
83

84
  // Setup click interactions and drag functionality
85
  function setupInteractions() {
86
    const canvas = document.getElementById("live2d-canvas");
87
    const container = document.getElementById("live2d-widget");
88
    if (!canvas || !container) return;
89

90
    canvas.addEventListener("click", handleClick);
91

92
    // 添加拖拽功能
93
    let isDragging = false;
94
    let dragStart = { x: 0, y: 0 };
95
    let containerStart = { x: 0, y: 0 };
96

97
    // 鼠标事件
98
    container.addEventListener("mousedown", (e) => {
99
      if (e.button !== 0) return; // 只响应左键
100
      isDragging = true;
101
      dragStart = { x: e.clientX, y: e.clientY };
102

103
      const rect = container.getBoundingClientRect();
104
      containerStart = { x: rect.left, y: rect.top };
105

106
      container.style.cursor = "grabbing";
107
      e.preventDefault();
108
    });
109

110
    document.addEventListener("mousemove", (e) => {
111
      if (!isDragging) return;
112

113
      const deltaX = e.clientX - dragStart.x;
114
      const deltaY = e.clientY - dragStart.y;
115

116
      const newX = containerStart.x + deltaX;
117
      const newY = containerStart.y + deltaY;
118

119
      // 边界检查
120
      const maxX = window.innerWidth - container.offsetWidth;
121
      const maxY = window.innerHeight - container.offsetHeight;
122

123
      const clampedX = Math.max(0, Math.min(newX, maxX));
124
      const clampedY = Math.max(0, Math.min(newY, maxY));
125

126
      container.style.left = clampedX + "px";
127
      container.style.right = "auto";
128
      container.style.top = clampedY + "px";
129
      container.style.bottom = "auto";
130
    });
131

132
    document.addEventListener("mouseup", () => {
133
      if (isDragging) {
134
        isDragging = false;
135
        container.style.cursor = "grab";
136
      }
137
    });
138

139
    // 触摸事件（移动端支持）
140
    container.addEventListener("touchstart", (e) => {
141
      if (e.touches.length !== 1) return;
142
      isDragging = true;
143
      const touch = e.touches[0];
144
      dragStart = { x: touch.clientX, y: touch.clientY };
145

146
      const rect = container.getBoundingClientRect();
147
      containerStart = { x: rect.left, y: rect.top };
148

149
      e.preventDefault();
150
    });
151

152
    document.addEventListener("touchmove", (e) => {
153
      if (!isDragging || e.touches.length !== 1) return;
154

155
      const touch = e.touches[0];
156
      const deltaX = touch.clientX - dragStart.x;
157
      const deltaY = touch.clientY - dragStart.y;
158

159
      const newX = containerStart.x + deltaX;
160
      const newY = containerStart.y + deltaY;
161

162
      // 边界检查
163
      const maxX = window.innerWidth - container.offsetWidth;
164
      const maxY = window.innerHeight - container.offsetHeight;
165

166
      const clampedX = Math.max(0, Math.min(newX, maxX));
167
      const clampedY = Math.max(0, Math.min(newY, maxY));
168

169
      container.style.left = clampedX + "px";
170
      container.style.right = "auto";
171
      container.style.top = clampedY + "px";
172
      container.style.bottom = "auto";
173

174
      e.preventDefault();
175
    });
176

177
    document.addEventListener("touchend", () => {
178
      isDragging = false;
179
    });
180

181
    // 设置初始光标样式
182
    container.style.cursor = "grab";
183

184
    // 窗口大小变化时重新检查边界
185
    window.addEventListener("resize", () => {
186
      const rect = container.getBoundingClientRect();
187
      const maxX = window.innerWidth - container.offsetWidth;
188
      const maxY = window.innerHeight - container.offsetHeight;
189

190
      if (rect.left > maxX) {
191
        container.style.left = maxX + "px";
192
        container.style.right = "auto";
193
      }
194
      if (rect.top > maxY) {
195
        container.style.top = maxY + "px";
196
        container.style.bottom = "auto";
197
      }
198
    });
199

200
    console.log("Live2D interactions and drag functionality setup complete");
201
  }
202

203
  // Handle click events
204
  function handleClick(event) {
205
    if (!motionGroups || Object.keys(motionGroups).length === 0) {
206
      console.log("No motion groups available");
207
      return;
208
    }
209

210
    const rect = event.target.getBoundingClientRect();
211
    const x = event.clientX - rect.left;
212
    const y = event.clientY - rect.top;
213

214
    // Convert to normalized coordinates
215
    const normalizedX = (x / rect.width) * 2 - 1;
216
    const normalizedY = -((y / rect.height) * 2 - 1);
217

218
    console.log("Click at:", { x: normalizedX, y: normalizedY });
219

220
    // Determine which motion to play based on hit areas
221
    let motionGroup = "tap_body"; // default
222

223
    // Check head area
224
    if (hitAreas.head_x && hitAreas.head_y) {
225
      const [headXMin, headXMax] = hitAreas.head_x;
226
      const [headYMin, headYMax] = hitAreas.head_y;
227

228
      if (
229
        normalizedX >= headXMin &&
230
        normalizedX <= headXMax &&
231
        normalizedY >= headYMin &&
232
        normalizedY <= headYMax
233
      ) {
234
        motionGroup = "flick_head";
235
        console.log("Head area clicked - playing flick_head motion");
236
      }
237
    }
238

239
    // Check body area (if not head)
240
    if (motionGroup === "tap_body" && hitAreas.body_x && hitAreas.body_y) {
241
      const [bodyXMin, bodyXMax] = hitAreas.body_x;
242
      const [bodyYMin, bodyYMax] = hitAreas.body_y;
243

244
      if (
245
        normalizedX >= bodyXMin &&
246
        normalizedX <= bodyXMax &&
247
        normalizedY >= bodyYMin &&
248
        normalizedY <= bodyYMax
249
      ) {
250
        console.log("Body area clicked - playing tap_body motion");
251
      }
252
    }
253

254
    // Play motion
255
    playMotion(motionGroup);
256

257
    // Show message
258
    showMessage();
259
  }
260

261
  // 消息框功能已移至公共组件 MessageBox.astro
262

263
  // Show random message using the common MessageBox component
264
  function showMessage() {
265
    const messages = config.interactive?.clickMessages || [
266
      "你好！伊利雅~",
267
      "有什么需要帮助的吗？",
268
      "今天天气真不错呢！",
269
      "要不要一起玩游戏？",
270
      "记得按时休息哦！",
271
    ];
272

273
    const randomMessage = messages[Math.floor(Math.random() * messages.length)];
274

275
    // 使用公共消息框组件
276
    if (window.showModelMessage) {
277
      window.showModelMessage(randomMessage, {
278
        containerId: "live2d-widget",
279
        displayTime: config.interactive?.messageDisplayTime || 3000
280
      });
281
    }
282
  }
283

284
  // Play motion from a specific group
285
  function playMotion(groupName) {
286
    if (!motionGroups[groupName] || motionGroups[groupName].length === 0) {
287
      console.log(`No motions available for group: ${groupName}`);
288
      // Fallback to any available motion group
289
      const availableGroups = Object.keys(motionGroups).filter(
290
        (key) => motionGroups[key].length > 0
291
      );
292
      if (availableGroups.length > 0) {
293
        groupName = availableGroups[0];
294
        console.log(`Using fallback group: ${groupName}`);
295
      } else {
296
        return;
297
      }
298
    }
299

300
    const motions = motionGroups[groupName];
301
    let motionIndex;
302

303
    if (groupName === currentMotionGroup) {
304
      // Cycle through motions in the same group
305
      currentMotionIndex = (currentMotionIndex + 1) % motions.length;
306
      motionIndex = currentMotionIndex;
307
    } else {
308
      // Random motion from new group
309
      motionIndex = Math.floor(Math.random() * motions.length);
310
      currentMotionIndex = motionIndex;
311
    }
312

313
    currentMotionGroup = groupName;
314

315
    console.log(`Playing motion ${motionIndex} from group ${groupName}`);
316

317
    // Trigger motion change by reloading model with different parameters
318
    // This is a workaround since we can't directly control motions in loadlive2d
319
    const canvas = document.getElementById("live2d-canvas");
320
    if (canvas && window.loadlive2d) {
321
      // Add motion info to canvas data for potential future use
322
      canvas.dataset.currentMotionGroup = groupName;
323
      canvas.dataset.currentMotionIndex = motionIndex;
324

325
      // Trigger a visual feedback
326
      canvas.style.transform = "scale(1.05)";
327
      setTimeout(() => {
328
        canvas.style.transform = "scale(1)";
329
      }, 150);
330
    }
331
  }
332

333
  // Load Live2D and initialize
334
  function loadLive2DSDK() {
335
    // 检查移动端显示设置，如果隐藏则不加载运行时
336
    if (
337
      config.responsive?.hideOnMobile &&
338
      window.innerWidth <= (config.responsive.mobileBreakpoint || 768)
339
    ) {
340
      console.log("📱 Mobile device detected, skipping Live2D model initialization");
341
      const widget = document.getElementById("live2d-widget");
342
      if (widget) widget.style.display = "none";
343
      return;
344
    }
345

346
    // Check if Live2D SDK is already loaded
347
    if (window.loadlive2d) {
348
      initLive2D();
349
      return;
350
    }
351

352
    // Load Live2D SDK
353
    const script = document.createElement("script");
354
    script.src = sdkPath;
355
    script.onload = () => {
356
      // Wait a bit for the SDK to initialize
357
      setTimeout(() => {
358
        if (window.loadlive2d) {
359
          initLive2D();
360
        } else {
361
          console.error("loadlive2d function not found after loading SDK");
362
        }
363
      }, 100);
364
    };
365
    script.onerror = () => {
366
      console.error("Failed to load Live2D SDK");
367
    };
368
    document.head.appendChild(script);
369
  }
370

371
  // Handle responsive display
372
  function handleResponsive() {
373
    const widget = document.getElementById("live2d-widget");
374
    if (!widget) return;
375

376
    const responsive = config.responsive;
377
    if (responsive?.hideOnMobile) {
378
      const breakpoint = responsive.mobileBreakpoint || 768;
379
      if (window.innerWidth <= breakpoint) {
380
        widget.style.display = "none";
381
      } else {
382
        widget.style.display = "block";
383
      }
384
    }
385
  }
386

387
  // Initialize when ready (only once)
388
  if (document.readyState === "loading") {
389
    document.addEventListener("DOMContentLoaded", () => {
390
      // 检查是否已经初始化
391
      if (!window.live2dModelInitialized) {
392
        loadLive2DSDK();
393
        window.live2dModelInitialized = true;
394
      }
395
      handleResponsive();
396
    });
397
  } else {
398
    // 检查是否已经初始化
399
    if (!window.live2dModelInitialized) {
400
      loadLive2DSDK();
401
      window.live2dModelInitialized = true;
402
    }
403
    handleResponsive();
404
  }
405

406
  // Handle window resize for responsive behavior
407
  window.addEventListener("resize", handleResponsive);
408

409
  // 监听 Swup 页面切换事件（如果使用了 Swup）
410
  if (typeof window.swup !== "undefined" && window.swup.hooks) {
411
    window.swup.hooks.on("content:replace", () => {
412
      // 只更新响应式显示，不重新创建模型
413
      setTimeout(() => {
414
        handleResponsive();
415
      }, 100);
416
    });
417
  } else {
418
    // 如果 Swup 还未加载，监听启用事件
419
    document.addEventListener("swup:enable", () => {
420
      if (window.swup && window.swup.hooks) {
421
        window.swup.hooks.on("content:replace", () => {
422
          setTimeout(() => {
423
            handleResponsive();
424
          }, 100);
425
        });
426
      }
427
    });
428
  }
429
</script>
430

431
<style>
432
  .live2d-widget {
433
    position: fixed;
434
    z-index: 999;
435
    pointer-events: auto; /* 启用指针事件以支持拖拽 */
436
    cursor: grab; /* 默认显示拖拽光标 */
437
  }
438

439
  #live2d-canvas {
440
    pointer-events: auto;
441
    cursor: pointer;
442
    transition: all 0.3s ease;
443
    width: 100%;
444
    height: 100%;
445
  }
446

447
  .live2d-widget:hover #live2d-canvas {
448
    opacity: 1;
449
  }
450

451
  /* 拖拽时的光标样式 */
452
  .live2d-widget:active {
453
    cursor: grabbing;
454
  }
455
</style>

展开收起

新建src\components\widget\SpineModel.astro#

src\components\widget\SpineModel.astro展开收起

1
---
2
import { spineModelConfig } from "@/config/pioConfig";
3
import MessageBox from "./PioMessageBox.astro";
4
import { url } from "@/utils/url-utils";
5
---
6

7
<!-- Spine Web Player CSS 将在 script 中动态加载 -->{
8
  spineModelConfig.enable && (
9
    <div
10
      id="spine-model-container"
11
      style={`
12
      position: fixed;
13
      ${spineModelConfig.position.corner.includes("right") ? "right" : "left"}: ${spineModelConfig.position.offsetX}px;
14
      ${spineModelConfig.position.corner.includes("top") ? "top" : "bottom"}: ${spineModelConfig.position.offsetY}px;
15
      width: ${spineModelConfig.size.width}px;
16
      height: ${spineModelConfig.size.height}px;
17
      pointer-events: auto;
18
      z-index: 1000;
19
    `}
20
    >
21
      <div id="spine-player-container" style="width: 100%; height: 100%;" />
22
      <div id="spine-error" style="display: none;" />
23
    </div>
24
  )
25
}
26

27
<!-- 引入消息框组件 -->
28
<MessageBox />
29

30
<script define:vars={{ spineModelConfig, modelPath: url(spineModelConfig.model.path), atlasPath: url(spineModelConfig.model.path.replace(".json", ".atlas")), cssPath: url("/pio/static/spine-player.min.css"), jsPath: url("/pio/static/spine-player.min.js") }}>
31
  // 动态加载 Spine CSS（带本地备用）
32
  function loadSpineCSS() {
33
    if (!spineModelConfig.enable) return;
34

35
    // 检查是否已经加载
36
    const existingLink = document.querySelector('link[href*="spine-player"]');
37
    if (existingLink) return;
38

39
    // 首先尝试加载 CDN CSS
40
    const cdnLink = document.createElement("link");
41
    cdnLink.rel = "stylesheet";
42
    cdnLink.href =
43
      "https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/spine-player.min.css";
44

45
    // 监听加载失败事件，自动回退到本地文件
46
    cdnLink.onerror = function () {
47
      console.warn("⚠️ Spine CSS CDN failed, trying local fallback...");
48

49
      // 移除失败的 CDN link
50
      if (cdnLink.parentNode) {
51
        cdnLink.parentNode.removeChild(cdnLink);
52
      }
53

54
      // 创建本地备用 CSS link
55
      const localLink = document.createElement("link");
56
      localLink.rel = "stylesheet";
57
      localLink.href = cssPath;
58
      localLink.onerror = function () {
59
        console.error("❌ Failed to load Spine CSS");
60
      };
61

62
      document.head.appendChild(localLink);
63
    };
64

65
    document.head.appendChild(cdnLink);
66
  }
67

68
  // 消息框功能已移至公共组件 MessageBox.astro
69
  let isClickProcessing = false; // 防止重复点击的标志
70
  let lastClickTime = 0; // 记录最后一次点击时间
71

72
  // 全局变量，防止重复初始化
73
  window.spineModelInitialized = window.spineModelInitialized || false;
74
  window.spinePlayerInstance = window.spinePlayerInstance || null;
75

76
  // 消息显示函数 - 使用公共消息框组件
77
  function showMessage(message) {
78
    // 使用公共消息框组件
79
    if (window.showModelMessage) {
80
      window.showModelMessage(message, {
81
        containerId: "spine-model-container",
82
        displayTime: spineModelConfig.interactive.messageDisplayTime || 3000
83
      });
84
    }
85
  }
86

87
  // 更新响应式显示
88
  function updateResponsiveDisplay() {
89
    if (!spineModelConfig.enable) return;
90

91
    const container = document.getElementById("spine-model-container");
92
    if (!container) return;
93

94
    // 检查移动端显示设置
95
    if (
96
      spineModelConfig.responsive.hideOnMobile &&
97
      window.innerWidth <= spineModelConfig.responsive.mobileBreakpoint
98
    ) {
99
      container.style.display = "none";
100
    } else {
101
      container.style.display = "block";
102
    }
103
  }
104

105
  // 清理函数
106
  function cleanupSpineModel() {
107
    console.log("🧹 Cleaning up existing Spine model...");
108

109
    // 清理消息显示（使用公共组件）
110
    if (window.clearModelMessage) {
111
      window.clearModelMessage();
112
    }
113

114
    // 清理现有的播放器实例
115
    if (window.spinePlayerInstance) {
116
      try {
117
        if (window.spinePlayerInstance.dispose) {
118
          window.spinePlayerInstance.dispose();
119
        }
120
      } catch (e) {
121
        console.warn("Error disposing spine player:", e);
122
      }
123
      window.spinePlayerInstance = null;
124
    }
125

126
    // 清理容器内容
127
    const playerContainer = document.getElementById("spine-player-container");
128
    if (playerContainer) {
129
      playerContainer.innerHTML = "";
130
    }
131

132
    // 重置初始化标志
133
    window.spineModelInitialized = false;
134
  }
135

136
  async function initSpineModel() {
137
    if (!spineModelConfig.enable) return;
138

139
    // 检查移动端显示设置，如果隐藏则不加载运行时
140
    if (
141
      spineModelConfig.responsive.hideOnMobile &&
142
      window.innerWidth <= spineModelConfig.responsive.mobileBreakpoint
143
    ) {
144
      console.log("📱 Mobile device detected, skipping Spine model initialization");
145
      const container = document.getElementById("spine-model-container");
146
      if (container) container.style.display = "none";
147
      return;
148
    }
149

150
    // 检查是否已经初始化
151
    if (window.spineModelInitialized) {
152
      console.log("⏭️ Spine model already initialized, skipping...");
153
      return;
154
    }
155

156
    console.log("🎯 Initializing Spine Model...");
157

158
    // 先清理可能存在的旧实例
159
    cleanupSpineModel();
160

161
    // 首先加载 CSS
162
    loadSpineCSS();
163

164
    // 加载 Spine Web Player 运行时
165
    const loadSpineRuntime = () => {
166
      return new Promise((resolve, reject) => {
167
        if (typeof window.spine !== "undefined") {
168
          console.log("✅ Spine runtime already loaded");
169
          resolve();
170
          return;
171
        }
172

173
        console.log("📦 Loading Spine runtime...");
174
        const script = document.createElement("script");
175
        script.src =
176
          "https://unpkg.com/@esotericsoftware/spine-player@4.2.*/dist/iife/spine-player.min.js";
177
        script.onload = () => {
178
          console.log("✅ Spine runtime loaded from CDN");
179
          resolve();
180
        };
181
        script.onerror = (error) => {
182
          console.warn("⚠️ CDN failed, trying local fallback...");
183

184
          // 尝试本地回退
185
          const fallbackScript = document.createElement("script");
186
          fallbackScript.src = jsPath;
187
          fallbackScript.onload = () => {
188
            console.log("✅ Spine runtime loaded from local fallback");
189
            resolve();
190
          };
191
          fallbackScript.onerror = () => {
192
            reject(new Error("Failed to load Spine runtime"));
193
          };
194
          document.head.appendChild(fallbackScript);
195
        };
196
        document.head.appendChild(script);
197
      });
198
    };
199

200
    // 等待 Spine 库加载
201
    const waitForSpine = () => {
202
      return new Promise((resolve, reject) => {
203
        let attempts = 0;
204
        const maxAttempts = 50;
205

206
        const check = () => {
207
          attempts++;
208
          if (typeof window.spine !== "undefined" && window.spine.SpinePlayer) {
209
            console.log("✅ Spine runtime loaded");
210
            resolve();
211
          } else if (attempts >= maxAttempts) {
212
            reject(new Error("Spine runtime loading timeout"));
213
          } else {
214
            setTimeout(check, 100);
215
          }
216
        };
217
        check();
218
      });
219
    };
220

221
    try {
222
      // 首先加载 Spine 运行时
223
      await loadSpineRuntime();
224

225
      // 然后等待 Spine 对象可用
226
      await waitForSpine();
227

228
      // 标记为已初始化
229
      window.spineModelInitialized = true;
230

231
      // 创建 SpinePlayer
232
      const player = new window.spine.SpinePlayer("spine-player-container", {
233
        skeleton: modelPath,
234
        atlas: atlasPath,
235
        animation: "idle",
236
        backgroundColor: "#00000000", // 透明背景
237
        showControls: false, // 隐藏控件
238
        alpha: true,
239
        premultipliedAlpha: false,
240
        success: (player) => {
241
          console.log("🎉 Spine model loaded successfully!");
242

243
          // 保存播放器实例引用
244
          window.spinePlayerInstance = player;
245

246
          // 初始化完成后设置默认姿态
247
          setTimeout(() => {
248
            if (player.skeleton) {
249
              try {
250
                player.skeleton.updateWorldTransform();
251
                player.skeleton.setToSetupPose();
252
              } catch (e) {
253
                console.warn("Error positioning skeleton:", e);
254
              }
255
            }
256
          }, 500);
257

258
          // 设置交互功能
259
          if (spineModelConfig.interactive.enabled) {
260
            const canvas = document.querySelector(
261
              "#spine-player-container canvas"
262
            );
263
            if (canvas) {
264
              canvas.addEventListener("click", () => {
265
                // 防抖处理：防止重复点击
266
                const currentTime = Date.now();
267
                if (isClickProcessing || currentTime - lastClickTime < 500) {
268
                  return; // 500ms 内重复点击忽略
269
                }
270

271
                isClickProcessing = true;
272
                lastClickTime = currentTime;
273

274
                // 随机播放点击动画
275
                const clickAnims =
276
                  spineModelConfig.interactive.clickAnimations ||
277
                  (spineModelConfig.interactive.clickAnimation
278
                    ? [spineModelConfig.interactive.clickAnimation]
279
                    : []);
280

281
                if (clickAnims.length > 0) {
282
                  try {
283
                    const randomClickAnim =
284
                      clickAnims[Math.floor(Math.random() * clickAnims.length)];
285
                    player.setAnimation(randomClickAnim, false);
286

287
                    // 动画播放完成后回到待机状态
288
                    setTimeout(() => {
289
                      const idleAnims =
290
                        spineModelConfig.interactive.idleAnimations;
291
                      const randomIdle =
292
                        idleAnims[Math.floor(Math.random() * idleAnims.length)];
293
                      player.setAnimation(randomIdle, true);
294
                    }, 2000);
295
                  } catch (e) {
296
                    console.warn("Failed to play click animation:", e);
297
                  }
298
                }
299

300
                // 显示随机消息
301
                const messages = spineModelConfig.interactive.clickMessages;
302
                if (messages && messages.length > 0) {
303
                  const randomMessage =
304
                    messages[Math.floor(Math.random() * messages.length)];
305
                  showMessage(randomMessage);
306
                }
307

308
                // 500ms 后重置防抖标志
309
                setTimeout(() => {
310
                  isClickProcessing = false;
311
                }, 500);
312
              });
313

314
              // 设置待机动画循环
315
              if (spineModelConfig.interactive.idleAnimations.length > 1) {
316
                setInterval(() => {
317
                  try {
318
                    const idleAnims =
319
                      spineModelConfig.interactive.idleAnimations;
320
                    const randomIdle =
321
                      idleAnims[Math.floor(Math.random() * idleAnims.length)];
322
                    player.setAnimation(randomIdle, true);
323
                  } catch (e) {
324
                    console.warn("Failed to play idle animation:", e);
325
                  }
326
                }, spineModelConfig.interactive.idleInterval);
327
              }
328
            }
329
          }
330

331
          // 添加拖拽功能
332
          const container = document.getElementById("spine-model-container");
333
          if (container) {
334
            let isDragging = false;
335
            let dragStart = { x: 0, y: 0 };
336
            let containerStart = { x: 0, y: 0 };
337

338
            // 鼠标事件
339
            container.addEventListener("mousedown", (e) => {
340
              if (e.button !== 0) return; // 只响应左键
341
              isDragging = true;
342
              dragStart = { x: e.clientX, y: e.clientY };
343

344
              const rect = container.getBoundingClientRect();
345
              containerStart = { x: rect.left, y: rect.top };
346

347
              container.style.cursor = "grabbing";
348
              e.preventDefault();
349
            });
350

351
            document.addEventListener("mousemove", (e) => {
352
              if (!isDragging) return;
353

354
              const deltaX = e.clientX - dragStart.x;
355
              const deltaY = e.clientY - dragStart.y;
356

357
              const newX = containerStart.x + deltaX;
358
              const newY = containerStart.y + deltaY;
359

360
              // 边界检查
361
              const maxX = window.innerWidth - container.offsetWidth;
362
              const maxY = window.innerHeight - container.offsetHeight;
363

364
              const clampedX = Math.max(0, Math.min(newX, maxX));
365
              const clampedY = Math.max(0, Math.min(newY, maxY));
366

367
              container.style.left = clampedX + "px";
368
              container.style.right = "auto";
369
              container.style.top = clampedY + "px";
370
              container.style.bottom = "auto";
371
            });
372

373
            document.addEventListener("mouseup", () => {
374
              if (isDragging) {
375
                isDragging = false;
376
                container.style.cursor = "grab";
377
              }
378
            });
379

380
            // 触摸事件（移动端支持）
381
            container.addEventListener("touchstart", (e) => {
382
              if (e.touches.length !== 1) return;
383
              isDragging = true;
384
              const touch = e.touches[0];
385
              dragStart = { x: touch.clientX, y: touch.clientY };
386

387
              const rect = container.getBoundingClientRect();
388
              containerStart = { x: rect.left, y: rect.top };
389

390
              e.preventDefault();
391
            });
392

393
            document.addEventListener("touchmove", (e) => {
394
              if (!isDragging || e.touches.length !== 1) return;
395

396
              const touch = e.touches[0];
397
              const deltaX = touch.clientX - dragStart.x;
398
              const deltaY = touch.clientY - dragStart.y;
399

400
              const newX = containerStart.x + deltaX;
401
              const newY = containerStart.y + deltaY;
402

403
              // 边界检查
404
              const maxX = window.innerWidth - container.offsetWidth;
405
              const maxY = window.innerHeight - container.offsetHeight;
406

407
              const clampedX = Math.max(0, Math.min(newX, maxX));
408
              const clampedY = Math.max(0, Math.min(newY, maxY));
409

410
              container.style.left = clampedX + "px";
411
              container.style.right = "auto";
412
              container.style.top = clampedY + "px";
413
              container.style.bottom = "auto";
414

415
              e.preventDefault();
416
            });
417

418
            document.addEventListener("touchend", () => {
419
              isDragging = false;
420
            });
421

422
            // 设置初始光标样式
423
            container.style.cursor = "grab";
424

425
            // 窗口大小变化时重新检查边界
426
            window.addEventListener("resize", () => {
427
              const rect = container.getBoundingClientRect();
428
              const maxX = window.innerWidth - container.offsetWidth;
429
              const maxY = window.innerHeight - container.offsetHeight;
430

431
              if (rect.left > maxX) {
432
                container.style.left = maxX + "px";
433
                container.style.right = "auto";
434
              }
435
              if (rect.top > maxY) {
436
                container.style.top = maxY + "px";
437
                container.style.bottom = "auto";
438
              }
439
            });
440
          }
441

442
          console.log("✅ Spine model setup complete!");
443
        },
444
        error: (player, reason) => {
445
          console.error("❌ Spine model loading error:", reason);
446

447
          const errorDiv = document.getElementById("spine-error");
448
          if (errorDiv) {
449
            errorDiv.style.display = "block";
450
            errorDiv.innerHTML = `
451
              <div style="color: #ff4444; padding: 20px; text-align: center; font-size: 14px;">
452
                <div>⚠️ Spine 模型加载失败</div>
453
                <div style="font-size: 12px; margin-top: 8px; color: #888;">${reason}</div>
454
              </div>
455
            `;
456
          }
457

458
          const canvas = document.getElementById("spine-canvas");
459
          if (canvas) canvas.style.display = "none";
460
        },
461
      });
462
    } catch (error) {
463
      console.error("Spine model initialization error:", error);
464

465
      // 重置初始化标志，允许重试
466
      window.spineModelInitialized = false;
467

468
      const errorDiv = document.getElementById("spine-error");
469
      if (errorDiv) {
470
        errorDiv.style.display = "block";
471
        errorDiv.innerHTML = `
472
          <div style="color: #ff4444; padding: 20px; text-align: center; font-size: 14px;">
473
            <div>⚠️ Spine 运行时加载失败</div>
474
            <div style="font-size: 12px; margin-top: 8px; color: #888;">${error instanceof Error ? error.message : "未知错误"}</div>
475
          </div>
476
        `;
477
      }
478
    }
479
  }
480

481
  // 监听页面卸载事件，清理资源
482
  window.addEventListener("beforeunload", cleanupSpineModel);
483

484
  // 监听 Swup 页面切换事件（如果使用了 Swup）
485
  if (typeof window.swup !== "undefined" && window.swup.hooks) {
486
    window.swup.hooks.on("content:replace", () => {
487
      // 只更新响应式显示，不重新创建模型
488
      setTimeout(() => {
489
        updateResponsiveDisplay();
490
      }, 100);
491
    });
492
  }
493

494
  // 监听 popstate 事件（浏览器前进后退）
495
  window.addEventListener("popstate", () => {
496
    setTimeout(() => {
497
      updateResponsiveDisplay();
498
    }, 100);
499
  });
500

501
  // 监听窗口大小变化
502
  window.addEventListener("resize", updateResponsiveDisplay);
503

504
  // 页面加载完成后初始化（只初始化一次）
505
  if (document.readyState === "loading") {
506
    document.addEventListener("DOMContentLoaded", initSpineModel);
507
  } else {
508
    initSpineModel();
509
  }
510
</script>

展开收起

修改src\layouts\MainGridLayout.astro#

src\layouts\MainGridLayout.astro展开收起

1
---
2
 // 。。。。省略
3
import SpineModel from "@components/widget/SpineModel.astro";
4
import Live2DWidget from "@components/widget/Live2DWidget.astro";
5
import TOC from "../components/widget/TOC.astro";
6
import { siteConfig,live2dModelConfig } from "../config";
7
import {
8
  BANNER_HEIGHT,
9
  BANNER_HEIGHT_EXTEND,
10
  MAIN_PANEL_OVERLAPS_BANNER_HEIGHT,
11
} from "../constants/constants";
12
import Layout from "./Layout.astro";
13

14
---
15

16
<Layout title={title} banner={banner} description={description} lang={lang} setOGTypeArticle={setOGTypeArticle}>
17

18
// 。。。。省略
19

20
<!-- Main content -->
21
<div class="absolute w-full z-30 pointer-events-none" style={`top: ${mainPanelTop}`}>
22
            <div class="footer col-span-2 onload-animation block lg:hidden">
23
                <Footer></Footer>
24
            </div>
25
        </div>
26
    <!-- 直接搜 BackToTop -->
27
        <BackToTop></BackToTop>
28

29
        <SpineModel></SpineModel>
30
        {live2dModelConfig.enable && <Live2DWidget config={live2dModelConfig} />}
31
    </div>
32
</div>
33
        <!-- #toc needs to exist for Swup to work normally -->
34
        {!siteConfig.toc.enable && <div id="toc"></div>}
35
    </div>
36
</div>
37
</Layout>

展开收起

性能优化建议#

1. 模型选择#

1
// 选择轻量级模型
2
model: {
3
  path: "/pio/models/spine/simple-model.json", // 简单模型
4
  scale: 0.8,  // 适当缩小
5
}

2. 动画控制#

1
interactive: {
2
  idleInterval: 10000,  // 增加待机动画间隔
3
  clickAnimations: ["simple_click"], // 减少点击动画数量
4
}

3. 响应式设置#

1
responsive: {
2
  hideOnMobile: true,        // 移动端隐藏
3
  mobileBreakpoint: 1024,    // 提高断点
4
}

常见问题#

Q: 看板娘不显示怎么办？#

A: 检查以下项目：

enable 是否设置为 true
模型文件路径是否正确
模型文件是否完整
浏览器控制台是否有错误

Q: 如何更换看板娘模型？#

A: 修改 model.path 路径：

1
model: {
2
  path: "/pio/models/spine/new-model/model.json",
3
}

Q: 如何调整看板娘大小？#

A: 修改 size 配置：

1
size: {
2
  width: 200,   // 调整宽度
3
  height: 250,  // 调整高度
4
}

Q: 如何添加更多点击消息？#

A: 在 clickMessages 数组中添加：

1
clickMessages: [
2
  "原有消息1",
3
  "原有消息2",
4
  "新消息1",  // 添加新消息
5
  "新消息2",  // 添加新消息
6
]

注意事项#

性能考虑：看板娘会增加页面加载时间，建议在移动端隐藏
文件大小：模型文件较大，建议压缩纹理图片
浏览器兼容：某些旧浏览器可能不支持WebGL
版权问题：使用模型时注意版权许可
用户体验：避免过于频繁的动画影响阅读体验

高级配置#

自定义动画序列#

1
interactive: {
2
  clickAnimations: [
3
    "wave",      // 挥手动画
4
    "jump",      // 跳跃动画
5
    "dance",     // 舞蹈动画
6
    "sleep"      // 睡觉动画
7
  ],
8
  idleAnimations: [
9
    "idle",      // 基础待机
10
    "blink",     // 眨眼
11
    "look_around" // 四处张望
12
  ],
13
}

动态消息系统#

1
clickMessages: [
2
  "现在是${new Date().getHours()}点哦~",
3
  "今天天气${weather}呢！",
4
  "欢迎第${visitCount}次访问！"
5
]

条件显示#

1
// 根据时间显示不同消息
2
const getTimeMessage = () => {
3
  const hour = new Date().getHours();
4
  if (hour < 12) return "早上好！";
5
  if (hour < 18) return "下午好！";
6
  return "晚上好！";
7
};

随机封面图配置

Sat, 08 Nov 2025 00:00:00 GMT

前言#

写文章配插图，文章中的图片好说，这个封面就不太行了，好多时候都会忘记这回事，毕竟写文章的软件是Typora 写完我就直接上传了，谁还管封面啊！以前采用的WordPress 会自动把文章的第一张图片设置为封面，但是Astro Fuwari 没有自动封面这个功能，因此我写下这篇文章作为参考。

两种方案，一种是修改地方少，一种是模块化设计(大改)

方案一#

修改 scripts/new-post.js 文件，为每篇新文章添加从 boxmoe API 获取的随机图片作为封面。

当用户通过pnpm new-post <fileName> 时，在新创建的文章 front-matter 中，将 image 字段的值设置为这个随机图片 API 地址

new-post.js展开收起

1
/* This is a script to create a new post markdown file with front-matter */
2

3
import fs from "node:fs";
4
import path from "node:path";
5

6
function getDate() {
7
  const today = new Date();
8
  const year = today.getFullYear();
9
  const month = String(today.getMonth() + 1).padStart(2, "0");
10
  const day = String(today.getDate()).padStart(2, "0");
11

12
  return `${year}-${month}-${day}`;
13
}
14

15
// Function to get random image from boxmoe API with unique parameter
16
function getRandomImage() {
17
  // Generate a random number to make each image URL unique
18
  const randomParam = Math.random().toString(36).substring(2, 15);
19
  return `https://api.boxmoe.com/random.php?size=large&t=${randomParam}`;
20
}
21

22
const args = process.argv.slice(2);
23

24
if (args.length === 0) {
25
  console.error(`Error: No filename argument provided
26
Usage: npm run new-post -- <filename>`);
27
  process.exit(1); // Terminate the script and return error code 1
28
}
29

30
let fileName = args[0];
31

32
// Add .md extension if not present
33
const fileExtensionRegex = /\.(md|mdx)$/i;
34
if (!fileExtensionRegex.test(fileName)) {
35
  fileName += ".md";
36
}
37

38
const targetDir = "./src/content/posts/";
39
const fullPath = path.join(targetDir, fileName);
40

41
if (fs.existsSync(fullPath)) {
42
  console.error(`Error: File ${fullPath} already exists `);
43
  process.exit(1);
44
}
45

46
// recursive mode creates multi-level directories
47
const dirPath = path.dirname(fullPath);
48
if (!fs.existsSync(dirPath)) {
49
  fs.mkdirSync(dirPath, { recursive: true });
50
}
51

52
const content = `---
53
title: ${args[0]}
54
published: ${getDate()}
55
updated: ${getDate()}
56
description: ''
57
image: '${getRandomImage()}'
58
tags: []
59
category: ''
60
draft: false
61
lang: ''
62
pinned: false
63
series: ''
64
---
65
`;
66

67
fs.writeFileSync(path.join(targetDir, fileName), content);
68

69
console.log(`Post ${fullPath} created`);

展开收起

方案二#

随机封面图功能允许文章使用 API 自动获取随机图片作为封面图。当 API 请求失败时，系统会自动切换到备用图片，确保封面图始终能够正常显示。此功能特别适合想要快速为文章添加封面图的用户。

基础配置#

基础配置展开收起

1
export const coverImageConfig: CoverImageConfig = {
2
  // 随机封面图功能开关
3
  enable: true,
4
  // 封面图API列表
5
  apis: [
6
    "https://t.alcy.cc/pc",
7
    "https://www.dmoe.cc/random.php",
8
    "https://uapis.cn/api/v1/random/image?category=acg&type=pc",
9
  ],
10
  // 备用图片路径
11
  fallback: "/assets/images/cover.webp",
12

13
  // 加载指示器配置
14
  loading: {
15
    image: "/assets/images/loading.gif",
16
    backgroundColor: "#fefefe",
17
  },
18

19
  // 水印配置
20
  watermark: {
21
    enable: true,
22
    text: "Random Cover",
23
    position: "bottom-right",
24
    opacity: 0.6,
25
    fontSize: "0.75rem",
26
    color: "#ffffff",
27
    backgroundColor: "rgba(0, 0, 0, 0.5)",
28
  },
29
};

展开收起

配置选项详解#

基础配置#

选项	类型	说明	必填	默认值
`enable`	`boolean`	随机封面图功能开关	是	`true`
`apis`	`string[]`	封面图API列表，系统会依次尝试	是	`[]`
`fallback`	`string`	备用图片路径（API全部失败时使用）	否	-

功能开关说明#

enable: true：启用随机封面图功能，文章使用 image: "api" 时会尝试从 API 获取图片
enable: false：禁用随机封面图功能，即使文章设置了 image: "api"，也不会显示封面图（也不会显示备用图）

API 列表配置#

系统会按照 apis 数组的顺序依次尝试每个 API：

1
apis: [
2
  "https://api1.example.com/image",  // 首先尝试这个
3
  "https://api2.example.com/image",  // 如果失败，尝试这个
4
  "https://api3.example.com/image",  // 如果还失败，尝试这个
5
]

API 选择逻辑：

系统按顺序尝试每个 API
如果某个 API 失败，自动尝试下一个
如果所有 API 都失败，使用备用图片（fallback）
失败的 API 会被记录到 localStorage，避免下次重复请求（F5 刷新会清除记录）

备用图片配置#

1
fallback: "/assets/images/cover.webp"

路径相对于 public 目录
支持相对路径（如 /assets/images/cover.webp）
当所有 API 都失败时，使用此图片作为封面
使用备用图片时，水印文字会自动更新为 “Image API Error”

加载指示器配置#

配置选项#

选项	类型	说明	必填	默认值
`image`	`string`	自定义加载图片路径（相对于 public 目录）	否	`"/assets/images/loading.gif"`
`backgroundColor`	`string`	加载指示器背景颜色	否	`"#fefefe"`

使用示例#

1
loading: {
2
  image: "/assets/images/my-loading.gif",  // 自定义加载 GIF
3
  backgroundColor: "#ffffff",                // 白色背景（与 GIF 背景色一致）
4
}

注意事项#

背景颜色匹配：backgroundColor 应该与加载 GIF 的背景色一致，避免在暗色模式下显得突兀
图片路径：路径相对于 public 目录，不需要包含 public
只对远程 API 图片生效：本地图片不会显示加载指示器

水印配置#

配置选项#

选项	类型	说明	必填	默认值
`enable`	`boolean`	水印开关	是	`true`
`text`	`string`	水印文本	否	`"Random Cover"`
`position`	`string`	水印位置	否	`"bottom-right"`
`opacity`	`number`	水印透明度（0-1）	否	`0.6`
`fontSize`	`string`	字体大小	否	`"0.75rem"`
`color`	`string`	文字颜色	否	`"#ffffff"`
`backgroundColor`	`string`	背景颜色	否	`"rgba(0, 0, 0, 0.5)"`

水印位置选项#

位置值	说明	移动端显示	桌面端显示
`"top-left"`	左上角	左上角	左上角
`"top-right"`	右上角	右上角	右上角
`"bottom-left"`	左下角	左上角（避免被裁剪）	左下角
`"bottom-right"`	右下角	右上角（避免被裁剪）	右下角
`"center"`	居中	居中	居中

注意：bottom-left 和 bottom-right 在移动端会自动调整到顶部显示，避免水印被裁剪。

水印文字规则#

API 成功时：显示配置的 text（默认 “Random Cover”）
API 失败时：自动更新为 “Image API Error”
仅对远程 API 图片显示：本地图片不显示水印

使用示例#

1
watermark: {
2
  enable: true,
3
  text: "随机封面",           // 中文水印
4
  position: "bottom-right",   // 右下角
5
  opacity: 0.8,               // 更高透明度
6
  fontSize: "0.875rem",       // 稍大字体
7
  color: "#ff0000",           // 红色文字
8
  backgroundColor: "rgba(255, 255, 255, 0.9)", // 白色半透明背景
9
}

代码修改#

新建src\config\coverImageConfig.ts#

src\config\coverImageConfig.ts展开收起

1
import type { CoverImageConfig } from "../types/config";
2

3
/**
4
 * 文章随机封面图配置
5
 *
6
 * 使用说明：
7
 * 1. 在文章的 Frontmatter 中添加 image: "api" 即可使用随机图功能
8
 * 2. 系统会依次尝试所有配置的 API，全部失败后使用备用图片
9
 * 3. 如果 enable 为 false，则直接不显示封面图（也不会显示备用图）
10
 *
11
 * // 文章 Frontmatter 示例：
12
 * ---
13
 * title: 文章标题
14
 * image: "api"
15
 * ---
16
 */
17
export const coverImageConfig: CoverImageConfig = {
18
  // 随机封面图功能开关
19
  enable: true,
20
  // 封面图API列表
21
  apis: [
22
    "https://t.alcy.cc/pc",
23
    "https://www.dmoe.cc/random.php",
24
    "https://uapis.cn/api/v1/random/image?category=acg&type=pc",
25
  ],
26
  // 备用图片路径
27
  fallback: "/assets/images/cover.webp",
28

29
  /**
30
   * 加载指示器配置
31
   * - 自定义加载图片和背景色，用于在图片加载过程中显示
32
   * - 如果不配置，将使用默认的 loading.gif 和 #fefefe 背景色
33
   */
34
  loading: {
35
    // 自定义加载图片路径（相对于 public 目录）
36
    image: "/assets/images/loading.gif",
37
    // 加载指示器背景颜色，应与加载图片的背景色一致，避免在暗色模式下显得突兀
38
    backgroundColor: "#fefefe",
39
  },
40

41
  /**
42
   * 水印配置
43
   * - 仅在随机图API成功加载时显示水印
44
   * - 当使用备用图片时，水印文字会自动更新为 "Image API Error"
45
   * - 移动端会自动调整位置（bottom位置会显示在top，避免被裁剪）
46
   */
47
  watermark: {
48
    // 水印开关
49
    enable: true,
50
    // 水印文本
51
    text: "鹏星",
52
    /**
53
     * 水印位置
54
     * - "top-left": 左上角
55
     * - "top-right": 右上角
56
     * - "bottom-left": 左下角（移动端显示在左上角，桌面端显示在左下角）
57
     * - "bottom-right": 右下角（移动端显示在右上角，桌面端显示在右下角）
58
     * - "center": 居中
59
     */
60
    position: "bottom-right",
61
    // 水印透明度
62
    opacity: 0.6,
63
    // 字体大小
64
    fontSize: "0.75rem",
65
    // 字体颜色
66
    color: "#ffffff",
67
    // 背景颜色
68
    backgroundColor: "rgba(0, 0, 0, 0.5)",
69
  },
70
};

展开收起

新增src\types\config.ts中coverImageConfig类型#

src\types\config.ts展开收起

1
// 。。。。省略
2

3
export type CoverImageConfig = {
4
  enable: boolean; // 是否启用随机图功能
5
  apis: string[]; // 随机图API列表，支持 {seed} 占位符，会替换为文章slug或时间戳
6
  fallback?: string; // 当API请求失败时的备用图片路径
7
  // 加载指示器配置
8
  loading?: {
9
    image?: string; // 自定义加载图片路径（相对于public目录），默认 "/assets/images/loading.gif"
10
    backgroundColor?: string; // 加载指示器背景颜色，默认与loading.gif背景色一致 (#fefefe)
11
  };
12
  watermark?: {
13
    enable: boolean; // 是否显示水印
14
    text?: string; // 水印文本，默认为"随机图"
15
    position?:
16
      | "top-left"
17
      | "top-right"
18
      | "bottom-left"
19
      | "bottom-right"
20
      | "center"; // 水印位置
21
    opacity?: number; // 水印透明度 0-1，默认0.6
22
    fontSize?: string; // 字体大小，默认"0.75rem"
23
    color?: string; // 文字颜色，默认为白色
24
    backgroundColor?: string; // 背景颜色，默认为半透明黑色
25
  };
26
};

展开收起

新建src\utils\image-utils.ts#

src\utils\image-utils.ts展开收起

1
import { coverImageConfig } from "@/config/coverImageConfig";
2

3
/**
4
 * 处理文章封面图
5
 * 当image字段为"api"时，从配置的随机图API获取图片
6
 * @param image - 文章frontmatter中的image字段值
7
 * @param seed - 用于生成随机图的种子（通常使用文章slug或id）
8
 * @returns 处理后的图片URL
9
 */
10
export async function processCoverImage(
11
  image: string | undefined,
12
  seed?: string,
13
): Promise<string> {
14
  // 如果image不存在或为空，直接返回
15
  if (!image || image === "") {
16
    return "";
17
  }
18

19
  // 如果image不是"api"，直接返回原始值
20
  if (image !== "api") {
21
    return image;
22
  }
23

24
  // 如果未启用随机图功能，直接返回空字符串（不显示封面，也不显示备用图）
25
  if (
26
    !coverImageConfig.enable ||
27
    !coverImageConfig.apis ||
28
    coverImageConfig.apis.length === 0
29
  ) {
30
    return "";
31
  }
32

33
  try {
34
    // 随机选择一个API
35
    const randomApi =
36
      coverImageConfig.apis[
37
        Math.floor(Math.random() * coverImageConfig.apis.length)
38
      ];
39

40
    // 生成seed值：使用文章slug或时间戳
41
    const seedValue = seed || Date.now().toString();
42

43
    // 如果API中包含{seed}占位符，替换它
44
    let apiUrl = randomApi.replace(/{seed}/g, seedValue);
45

46
    // 如果API中没有{seed}占位符，需要添加随机参数确保每篇文章获取不同图片
47
    if (!randomApi.includes("{seed}")) {
48
      // 将seed转换为数字hash（确保每个不同的slug产生不同的hash）
49
      const hash = seedValue.split("").reduce((acc, char) => {
50
        return ((acc << 5) - acc + char.charCodeAt(0)) | 0;
51
      }, 0);
52

53
      // 添加查询参数来确保每篇文章获取不同的图片
54
      const separator = apiUrl.includes("?") ? "&" : "?";
55
      // 使用hash确保每篇文章有不同的URL（稳定且唯一，基于文章slug）
56
      // 注意：如果API不支持查询参数来获取不同图片，可能需要配置支持seed占位符的API
57
      apiUrl = `${apiUrl}${separator}v=${Math.abs(hash)}`;
58
    }
59

60
    // 在构建时直接返回API URL（客户端会请求）
61
    // 注意：如果API返回的是JSON格式，需要特殊处理
62
    return apiUrl;
63
  } catch (error) {
64
    console.warn("Failed to process random image API:", error);
65
    // 即使出错，如果enable为false也不返回fallback，直接返回空字符串
66
    if (!coverImageConfig.enable) {
67
      return "";
68
    }
69
    return coverImageConfig.fallback || "";
70
  }
71
}
72

73
/**
74
 * 同步版本（用于不需要异步的场景）
75
 * 当image字段为"api"时，返回第一个API URL，客户端会依次尝试所有API
76
 */
77
export function processCoverImageSync(
78
  image: string | undefined,
79
  seed?: string,
80
): string {
81
  // 如果image不存在或为空，直接返回
82
  if (!image || image === "") {
83
    return "";
84
  }
85

86
  // 如果image不是"api"，直接返回原始值
87
  if (image !== "api") {
88
    return image;
89
  }
90

91
  // 如果未启用随机图功能，直接返回空字符串（不显示封面，也不显示备用图）
92
  if (
93
    !coverImageConfig.enable ||
94
    !coverImageConfig.apis ||
95
    coverImageConfig.apis.length === 0
96
  ) {
97
    return "";
98
  }
99

100
  try {
101
    // 返回第一个API，客户端脚本会依次尝试所有API
102
    const firstApi = coverImageConfig.apis[0];
103

104
    // 生成seed值：使用文章slug或时间戳
105
    const seedValue = seed || Date.now().toString();
106

107
    // 如果API中包含{seed}占位符，替换它
108
    let apiUrl = firstApi.replace(/{seed}/g, seedValue);
109

110
    // 如果API中没有{seed}占位符，需要添加随机参数确保每篇文章获取不同图片
111
    if (!firstApi.includes("{seed}")) {
112
      // 将seed转换为数字hash（确保每个不同的slug产生不同的hash）
113
      const hash = seedValue.split("").reduce((acc, char) => {
114
        return ((acc << 5) - acc + char.charCodeAt(0)) | 0;
115
      }, 0);
116

117
      // 添加查询参数来确保每篇文章获取不同的图片
118
      const separator = apiUrl.includes("?") ? "&" : "?";
119
      // 使用hash确保每篇文章有不同的URL（稳定且唯一，基于文章slug）
120
      // 注意：如果API不支持查询参数来获取不同图片，可能需要配置支持seed占位符的API
121
      apiUrl = `${apiUrl}${separator}v=${Math.abs(hash)}`;
122
    }
123

124
    return apiUrl;
125
  } catch (error) {
126
    console.warn("Failed to process random image API:", error);
127
    // 即使出错，如果enable为false也不返回fallback，直接返回空字符串
128
    if (!coverImageConfig.enable) {
129
      return "";
130
    }
131
    return coverImageConfig.fallback || "";
132
  }
133
}
134

135
/**
136
 * 生成所有API URL列表（用于客户端重试）
137
 */
138
export function generateApiUrls(seed?: string): string[] {
139
  if (
140
    !coverImageConfig.enable ||
141
    !coverImageConfig.apis ||
142
    coverImageConfig.apis.length === 0
143
  ) {
144
    return [];
145
  }
146

147
  const seedValue = seed || Date.now().toString();
148
  const hash = seedValue.split("").reduce((acc, char) => {
149
    return ((acc << 5) - acc + char.charCodeAt(0)) | 0;
150
  }, 0);
151

152
  return coverImageConfig.apis.map((api) => {
153
    let apiUrl = api.replace(/{seed}/g, seedValue);
154

155
    if (!api.includes("{seed}")) {
156
      const separator = apiUrl.includes("?") ? "&" : "?";
157
      apiUrl = `${apiUrl}${separator}v=${Math.abs(hash)}`;
158
    }
159

160
    return apiUrl;
161
  });
162
}

展开收起

新建src\components\misc\RandomCoverImage.astro#

src\components\misc\RandomCoverImage.astro展开收起

1
---
2
import { Image } from "astro:assets";
3
import * as path from "node:path";
4
import { coverImageConfig } from "@/config/coverImageConfig";
5
import { generateApiUrls } from "@/utils/image-utils";
6
import { url } from "@/utils/url-utils";
7

8
interface Props {
9
  id?: string;
10
  src: string;
11
  class?: string;
12
  alt?: string;
13
  position?: string;
14
  basePath?: string;
15
  seed?: string; // 用于生成随机图API的种子（文章slug）
16
  preview?: boolean; // 是否是预览模式（文章列表页），true为预览模式（小尺寸），false为详情页（大尺寸）
17
  fallback?: string; // 图片加载失败时的备用图片
18
}
19

20
const {
21
  id,
22
  src,
23
  alt,
24
  position = "center",
25
  basePath = "/",
26
  seed,
27
  preview = false,
28
  fallback,
29
} = Astro.props;
30
const className = Astro.props.class;
31

32
const isLocal = !(
33
  src.startsWith("/") ||
34
  src.startsWith("http") ||
35
  src.startsWith("https") ||
36
  src.startsWith("data:")
37
);
38
const isPublic = src.startsWith("/");
39

40
// 检查是否是随机图API（包含query参数v=）
41
const isRandomApiImage =
42
  (src.startsWith("http://") || src.startsWith("https://")) &&
43
  src.includes("?v=");
44

45
// TODO temporary workaround for images dynamic import
46
// https://github.com/withastro/astro/issues/3373
47
// biome-ignore lint/suspicious/noImplicitAnyLet: <check later>
48
let img;
49
if (isLocal) {
50
  const files = import.meta.glob<ImageMetadata>("../../**", {
51
    import: "default",
52
  });
53
  let normalizedPath = path
54
    .normalize(path.join("../../", basePath, src))
55
    .replace(/\\/g, "/");
56
  const file = files[normalizedPath];
57
  if (!file) {
58
    console.error(
59
      `\n[ERROR] Image file not found: ${normalizedPath.replace("../../", "src/")}`,
60
    );
61
  }
62
  img = await file();
63
}
64
// 如果是随机图API，生成所有API URL列表用于客户端重试
65
let allApiUrls: string[] = [];
66
if (
67
  isRandomApiImage &&
68
  coverImageConfig.enable &&
69
  coverImageConfig.apis &&
70
  coverImageConfig.apis.length > 0
71
) {
72
  allApiUrls = generateApiUrls(seed);
73
}
74

75
// 确定fallback图片路径
76
let fallbackSrc = "";
77
if (isRandomApiImage) {
78
  if (coverImageConfig.enable) {
79
    fallbackSrc = fallback || coverImageConfig.fallback || "";
80
  }
81
} else {
82
  fallbackSrc = fallback || "";
83
}
84

85
// 处理fallback URL
86
const getFallbackUrl = (src: string): string => {
87
  if (!src) return "";
88
  if (src.startsWith("http://") || src.startsWith("https://")) {
89
    return src;
90
  }
91
  if (src.startsWith("/")) {
92
    return url(src);
93
  }
94
  return url(`/${src}`);
95
};
96

97
// 图片样式
98
const imageClass = "w-full h-full object-cover";
99
const imageStyle = `object-position: ${position || "center"}; image-rendering: -webkit-optimize-contrast;`;
100

101
// 水印配置
102
const watermark = coverImageConfig.watermark;
103
const showWatermark = isRandomApiImage && watermark?.enable;
104

105
// 生成水印位置样式和类名
106
const getWatermarkStyles = (
107
  pos?: string,
108
): { classes: string; styles: string } => {
109
  const position = pos || "bottom-right";
110
  let classes = "";
111
  let styles = "";
112

113
  switch (position) {
114
    case "top-left":
115
      classes = "top-2 left-2";
116
      break;
117
    case "top-right":
118
      classes = "top-2 right-2";
119
      break;
120
    case "bottom-left":
121
      classes = "top-2 left-2 md:top-auto md:bottom-2 md:left-2";
122
      break;
123
    case "bottom-right":
124
      classes = "top-2 right-2 md:top-auto md:bottom-2 md:right-2";
125
      break;
126
    case "center":
127
      classes = "top-1/2 left-1/2 -translate-x-1/2 -translate-y-1/2";
128
      break;
129
    default:
130
      classes = "top-2 right-2 md:top-auto md:bottom-2 md:right-2";
131
  }
132

133
  styles = `padding: 0.25rem 0.5rem; border-radius: 0.25rem; font-size: ${watermark?.fontSize || "0.75rem"}; color: ${watermark?.color || "#ffffff"}; background-color: ${watermark?.backgroundColor || "rgba(0, 0, 0, 0.4)"}; opacity: ${watermark?.opacity || 0.6}; pointer-events: none; z-index: 10; white-space: nowrap; user-select: none;`;
134

135
  return { classes, styles };
136
};
137

138
const watermarkStyles = showWatermark
139
  ? getWatermarkStyles(watermark?.position)
140
  : { classes: "", styles: "" };
141
---
142

143
<div id={id} class:list={[
144
  className,
145
  'overflow-hidden relative',
146
  preview ? 'min-h-[150px] md:min-h-0' : 'min-h-[300px]'
147
]}>
148
  <!-- 加载指示器：只对随机图API显示 -->
149
  {isRandomApiImage && (
150
    <div
151
      class="image-loading-indicator absolute inset-0 flex items-center justify-center z-20 transition-opacity duration-300"
152
      style={`background-color: ${coverImageConfig.loading?.backgroundColor || '#fefefe'};`}
153
    >
154
      <img
155
        src={url(coverImageConfig.loading?.image || "/assets/images/loading.gif")}
156
        alt="Loading..."
157
        class="w-24 h-24 md:w-32 md:h-32 opacity-80"
158
      />
159
    </div>
160
  )}
161

162
  <!-- 本地图片：使用 Astro Image 组件 -->
163
  {isLocal && img && (
164
    <Image
165
      src={img}
166
      alt={alt || ""}
167
      class:list={[
168
        imageClass,
169
        preview ? 'random-cover-preview-image' : 'random-cover-full-image'
170
      ]}
171
      style={imageStyle}
172
      width={preview ? 400 : 1200}
173
      height={preview ? 300 : 800}
174
      loading="lazy"
175
      format="webp"
176
      quality={preview ? 80 : 90}
177
      widths={preview ? [200, 400, 600] : [800, 1200, 1600, 2000]}
178
      sizes={preview ? "(max-width: 768px) 100vw, 28vw" : "(max-width: 768px) 100vw, (max-width: 1200px) 90vw, 1200px"}
179
    />
180
  )}
181

182
  <!-- 远程图片（包括随机图API和普通远程图片） -->
183
  {!isLocal && (
184
    <img
185
      src={isPublic ? url(src) : src}
186
      alt={alt || ""}
187
      class:list={[
188
        imageClass,
189
        preview ? 'random-cover-preview-image' : 'random-cover-full-image'
190
      ]}
191
      style={imageStyle}
192
      loading="lazy"
193
      decoding="async"
194
      data-preview={preview ? "true" : "false"}
195
      data-seed={seed || ""}
196
      data-api-urls={allApiUrls.length > 0 ? JSON.stringify(allApiUrls) : ""}
197
      data-fallback={fallbackSrc ? getFallbackUrl(fallbackSrc) : ""}
198
      data-api-index={allApiUrls.length > 0 ? "0" : ""}
199
      data-enable={isRandomApiImage ? (coverImageConfig.enable ? "true" : "false") : ""}
200
      data-need-check-fallback="true"
201
    onloadstart={`(function(img){
202
      const container = img.parentElement;
203
      if (container) {
204
        const loadingIndicator = container.querySelector('.image-loading-indicator');
205
        if (loadingIndicator) {
206
          loadingIndicator.classList.remove('hidden');
207
          loadingIndicator.style.removeProperty('opacity');
208
          loadingIndicator.style.removeProperty('display');
209
        }
210
      }
211
    })(this);`}
212
    onload={`(function(img){
213
      if (img.naturalWidth > 0 && img.naturalHeight > 0) {
214
        setTimeout(function() {
215
          const container = img.parentElement;
216
          if (container) {
217
            const loadingIndicator = container.querySelector('.image-loading-indicator');
218
            if (loadingIndicator) {
219
              loadingIndicator.style.setProperty('opacity', '0', 'important');
220
              loadingIndicator.style.setProperty('transition', 'opacity 0.3s ease-out', 'important');
221
              setTimeout(function() {
222
                loadingIndicator.style.setProperty('display', 'none', 'important');
223
                loadingIndicator.classList.add('hidden');
224
              }, 300);
225
            }
226
            const watermarkEl = container.querySelector('[data-watermark]');
227
            if (watermarkEl && watermarkEl.getAttribute('data-watermark-visible') !== 'true') {
228
              watermarkEl.setAttribute('data-watermark-visible', 'true');
229
              watermarkEl.classList.remove('opacity-0');
230
              watermarkEl.classList.add('opacity-100');
231
              const originalOpacity = watermarkEl.getAttribute('data-original-opacity') || '0.6';
232
              watermarkEl.style.opacity = originalOpacity;
233
            }
234
          }
235
        }, 800);
236
      }
237
    })(this);`}
238
    onerror={`(function(img){
239
      try {
240
        const apiUrls = img.dataset.apiUrls ? JSON.parse(img.dataset.apiUrls) : [];
241
        let currentIndex = parseInt(img.dataset.apiIndex || '0');
242
        const isEnabled = img.dataset.enable !== 'false';
243
        const fallbackUrl = img.dataset.fallback;
244

245
        if (apiUrls.length > 0 && currentIndex < apiUrls.length - 1) {
246
          currentIndex = currentIndex + 1;
247
          img.dataset.apiIndex = currentIndex.toString();
248
          img.src = apiUrls[currentIndex];
249
        }
250
        else if (isEnabled && fallbackUrl && fallbackUrl.length > 0) {
251
          const seed = img.dataset.seed;
252
          if (seed) {
253
            try {
254
              localStorage.setItem('api_image_failed_' + seed, 'true');
255
            } catch (e) {}
256
          }
257
          const container = img.parentElement;
258
          if (container) {
259
            const watermarkEl = container.querySelector('[data-watermark]');
260
            if (watermarkEl) {
261
              watermarkEl.textContent = 'Image API Error';
262
              watermarkEl.setAttribute('data-error', 'true');
263
            }
264
          }
265
          img.onerror = null;
266
          img.src = fallbackUrl;
267
          img.addEventListener('load', function() {
268
            if (img.naturalWidth > 0 && img.naturalHeight > 0) {
269
              const container = img.parentElement;
270
              if (container) {
271
                const loadingIndicator = container.querySelector('.image-loading-indicator');
272
                if (loadingIndicator) {
273
                  loadingIndicator.style.opacity = '0';
274
                  setTimeout(function() {
275
                    loadingIndicator.style.display = 'none';
276
                  }, 300);
277
                }
278
                const watermarkEl = container.querySelector('[data-watermark]');
279
                if (watermarkEl && watermarkEl.getAttribute('data-watermark-visible') !== 'true') {
280
                  watermarkEl.setAttribute('data-watermark-visible', 'true');
281
                  watermarkEl.classList.remove('opacity-0');
282
                  watermarkEl.classList.add('opacity-100');
283
                  const originalOpacity = watermarkEl.getAttribute('data-original-opacity') || '0.6';
284
                  watermarkEl.style.opacity = originalOpacity;
285
                  watermarkEl.style.setProperty('opacity', originalOpacity, 'important');
286
                }
287
              }
288
            }
289
          }, { once: true });
290
        }
291
        else {
292
          img.onerror = null;
293
          img.style.display = 'none';
294
          const container = img.parentElement;
295
          if (container) {
296
            const loadingIndicator = container.querySelector('.image-loading-indicator');
297
            if (loadingIndicator) {
298
              loadingIndicator.style.opacity = '0';
299
              setTimeout(function() {
300
                loadingIndicator.style.display = 'none';
301
              }, 300);
302
            }
303
          }
304
        }
305
      } catch(e) {
306
        const isEnabled = img.dataset.enable !== 'false';
307
        const fallbackUrl = img.dataset.fallback;
308
        const seed = img.dataset.seed;
309
        if (isEnabled && fallbackUrl && fallbackUrl.length > 0) {
310
          if (seed) {
311
            try {
312
              localStorage.setItem('api_image_failed_' + seed, 'true');
313
            } catch (e) {}
314
          }
315
          const container = img.parentElement;
316
          if (container) {
317
            const watermarkEl = container.querySelector('[data-watermark]');
318
            if (watermarkEl) {
319
              watermarkEl.textContent = 'Image API Error';
320
              watermarkEl.setAttribute('data-error', 'true');
321
            }
322
          }
323
          img.onerror = null;
324
          img.src = fallbackUrl;
325
        } else {
326
          img.onerror = null;
327
          img.style.display = 'none';
328
          const container = img.parentElement;
329
          if (container) {
330
            const loadingIndicator = container.querySelector('.image-loading-indicator');
331
            if (loadingIndicator) {
332
              loadingIndicator.style.opacity = '0';
333
              setTimeout(function() {
334
                loadingIndicator.style.display = 'none';
335
              }, 300);
336
            }
337
          }
338
        }
339
      }
340
    })(this);`}
341
    />
342
  )}
343

344
  {showWatermark && (
345
    <div
346
      data-watermark="true"
347
      data-watermark-visible="false"
348
      data-original-opacity={watermark?.opacity || "0.6"}
349
      class:list={["absolute", watermarkStyles.classes, "pointer-events-none", "z-10"]}
350
      style={`${watermarkStyles.styles} opacity: 0 !important;`}
351
    >
352
      {watermark?.text || "Random Cover"}
353
    </div>
354
  )}
355
</div>
356

357
<style>
358
  .image-loading-indicator {
359
    opacity: 1 !important;
360
    display: flex !important;
361
    visibility: visible !important;
362
    z-index: 20;
363
  }
364

365
  .image-loading-indicator.hidden {
366
    opacity: 0 !important;
367
    display: none !important;
368
    visibility: hidden !important;
369
  }
370

371
  img.random-cover-preview-image,
372
  img[data-preview="true"] {
373
    min-height: 150px;
374
    @media (min-width: 768px) {
375
      min-height: 0;
376
    }
377
    image-rendering: -webkit-optimize-contrast !important;
378
    image-rendering: auto !important;
379
    transform: translateZ(0);
380
    -webkit-transform: translateZ(0);
381
    will-change: transform;
382
    backface-visibility: hidden;
383
    -webkit-backface-visibility: hidden;
384
    -ms-interpolation-mode: bicubic;
385
    object-fit: cover !important;
386
    max-width: 100%;
387
    max-height: 100%;
388
    width: 100%;
389
    height: 100%;
390
  }
391

392
  img.random-cover-full-image {
393
    min-height: 300px;
394
    image-rendering: -webkit-optimize-contrast !important;
395
    image-rendering: auto !important;
396
    transform: translateZ(0);
397
    -webkit-transform: translateZ(0);
398
    object-fit: cover !important;
399
    width: 100%;
400
    height: 100%;
401
  }
402
</style>
403

404
<script is:inline>
405
  (function() {
406
    function isPageRefresh() {
407
      try {
408
        if (window.performance && window.performance.getEntriesByType) {
409
          const navEntries = window.performance.getEntriesByType('navigation');
410
          if (navEntries.length > 0) {
411
            const navType = navEntries[0].type;
412
            if (navType === 'reload' || navType === 'navigate') {
413
              return true;
414
            }
415
            if (navType === 'back_forward') {
416
              return false;
417
            }
418
          }
419
        }
420
        if (window.performance && window.performance.navigation) {
421
          const navType = window.performance.navigation.type;
422
          if (navType === 1 || navType === 0) {
423
            return true;
424
          }
425
          if (navType === 2) {
426
            return false;
427
          }
428
        }
429
        const refreshCheckKey = 'random_cover_image_last_init_time';
430
        const navigationCheckKey = 'random_cover_image_navigation_type';
431
        const now = Date.now();
432
        const lastInitTime = sessionStorage.getItem(refreshCheckKey);
433
        const lastNavType = sessionStorage.getItem(navigationCheckKey);
434

435
        if (!lastInitTime || (now - parseInt(lastInitTime)) > 10000) {
436
          sessionStorage.setItem(refreshCheckKey, now.toString());
437
          sessionStorage.setItem(navigationCheckKey, 'refresh');
438
          return true;
439
        }
440

441
        if (lastNavType === 'back_forward' && (now - parseInt(lastInitTime)) < 5000) {
442
          return false;
443
        }
444

445
        sessionStorage.setItem(refreshCheckKey, now.toString());
446
        sessionStorage.setItem(navigationCheckKey, 'refresh');
447
        return true;
448
      } catch (e) {
449
        console.warn('Unable to detect page refresh type, clearing cache as fallback', e);
450
        return true;
451
      }
452
    }
453

454
    function clearApiFailureCache() {
455
      try {
456
        const keysToRemove = [];
457
        for (let i = 0; i < localStorage.length; i++) {
458
          const key = localStorage.key(i);
459
          if (key && key.startsWith('api_image_failed_')) {
460
            keysToRemove.push(key);
461
          }
462
        }
463
        keysToRemove.forEach(function(key) {
464
          localStorage.removeItem(key);
465
        });
466
        if (keysToRemove.length > 0) {
467
          console.log('Cleared ' + keysToRemove.length + ' API failure records on page refresh');
468
        }
469
      } catch (e) {
470
        console.warn('Failed to clear API failure cache', e);
471
      }
472
    }
473

474
    function checkAndUseFallbackForFailedApis() {
475
      const allApiImages = document.querySelectorAll('img[data-seed][data-fallback][data-enable="true"]');
476

477
      allApiImages.forEach(function(img) {
478
        const seed = img.dataset.seed;
479
        const fallbackUrl = img.dataset.fallback;
480

481
        if (seed && fallbackUrl) {
482
          try {
483
            const failureKey = 'api_image_failed_' + seed;
484
            if (localStorage.getItem(failureKey) === 'true') {
485
              if (img.src !== fallbackUrl && !img.src.includes(fallbackUrl.split('?')[0])) {
486
                img.src = fallbackUrl;
487
              }
488
              const container = img.parentElement;
489
              if (container) {
490
                const watermarkEl = container.querySelector('[data-watermark]');
491
                if (watermarkEl) {
492
                  watermarkEl.textContent = 'Image API Error';
493
                  watermarkEl.setAttribute('data-error', 'true');
494
                  const loadingIndicator = container.querySelector('.image-loading-indicator');
495
                  if (img.complete && img.naturalWidth > 0 && img.naturalHeight > 0) {
496
                    if (loadingIndicator) {
497
                      loadingIndicator.style.opacity = '0';
498
                      setTimeout(function() {
499
                        loadingIndicator.style.display = 'none';
500
                      }, 300);
501
                    }
502
                    watermarkEl.setAttribute('data-watermark-visible', 'true');
503
                    watermarkEl.classList.remove('opacity-0');
504
                    watermarkEl.classList.add('opacity-100');
505
                    const originalOpacity = watermarkEl.getAttribute('data-original-opacity') || '0.6';
506
                    watermarkEl.style.opacity = originalOpacity;
507
                    watermarkEl.style.setProperty('opacity', originalOpacity, 'important');
508
                  } else {
509
                    img.addEventListener('load', function() {
510
                      if (img.naturalWidth > 0 && img.naturalHeight > 0) {
511
                        if (loadingIndicator) {
512
                          loadingIndicator.style.opacity = '0';
513
                          setTimeout(function() {
514
                            loadingIndicator.style.display = 'none';
515
                          }, 300);
516
                        }
517
                        watermarkEl.setAttribute('data-watermark-visible', 'true');
518
                        watermarkEl.classList.remove('opacity-0');
519
                        watermarkEl.classList.add('opacity-100');
520
                        const originalOpacity = watermarkEl.getAttribute('data-original-opacity') || '0.6';
521
                        watermarkEl.style.opacity = originalOpacity;
522
                        watermarkEl.style.setProperty('opacity', originalOpacity, 'important');
523
                      }
524
                    }, { once: true });
525
                  }
526
                }
527
              }
528
            }
529
          } catch (e) {}
530
        }
531
      });
532
    }
533

534
    function showLoadingIndicator(img) {
535
      if (!img.dataset.seed && img.dataset.preview !== 'true') {
536
        return;
537
      }
538
      const container = img.closest('[id]') || img.parentElement;
539
      if (container) {
540
        const loadingIndicator = container.querySelector('.image-loading-indicator');
541
        if (loadingIndicator) {
542
          loadingIndicator.classList.remove('hidden');
543
          loadingIndicator.style.removeProperty('opacity');
544
          loadingIndicator.style.removeProperty('display');
545
        }
546
      }
547
    }
548

549
    function hideLoadingIndicator(img) {
550
      if (!img.dataset.seed && img.dataset.preview !== 'true') {
551
        return;
552
      }
553
      const container = img.closest('[id]') || img.parentElement;
554
      if (container) {
555
        const loadingIndicator = container.querySelector('.image-loading-indicator');
556
        if (loadingIndicator) {
557
          setTimeout(function() {
558
            loadingIndicator.style.setProperty('opacity', '0', 'important');
559
            loadingIndicator.style.setProperty('transition', 'opacity 0.3s ease-out', 'important');
560
            setTimeout(function() {
561
              loadingIndicator.style.setProperty('display', 'none', 'important');
562
              loadingIndicator.classList.add('hidden');
563
            }, 300);
564
          }, 800);
565
        }
566
      }
567
    }
568

569
    function showWatermark(img) {
570
      if (!img.complete || img.naturalWidth === 0 || img.naturalHeight === 0) {
571
        return;
572
      }
573
      hideLoadingIndicator(img);
574
      const container = img.closest('[id]') || img.parentElement;
575
      if (container) {
576
        const watermarkEl = container.querySelector('[data-watermark]');
577
        if (watermarkEl && watermarkEl.getAttribute('data-watermark-visible') !== 'true') {
578
          watermarkEl.setAttribute('data-watermark-visible', 'true');
579
          watermarkEl.classList.remove('opacity-0');
580
          watermarkEl.classList.add('opacity-100');
581
          const originalOpacity = watermarkEl.getAttribute('data-original-opacity') || '0.6';
582
          watermarkEl.style.opacity = originalOpacity;
583
          watermarkEl.style.setProperty('opacity', originalOpacity, 'important');
584
        }
585
      }
586
    }
587

588
    function optimizePreviewImages() {
589
      const previewImages = document.querySelectorAll('img[data-preview="true"]');
590
      previewImages.forEach(function(img) {
591
        if (!img.complete || img.naturalWidth === 0 || img.naturalHeight === 0) {
592
          showLoadingIndicator(img);
593
          img.addEventListener('loadstart', function() {
594
            showLoadingIndicator(img);
595
          }, { once: true });
596
        }
597
      });
598
    }
599

600
    function setupObserver() {
601
      const observer = new MutationObserver(function(mutations) {
602
        mutations.forEach(function(mutation) {
603
          mutation.addedNodes.forEach(function(node) {
604
            if (node.nodeType === Node.ELEMENT_NODE) {
605
              const element = node;
606
              const apiImages = [];
607
              if (element.tagName === 'IMG' && element.dataset.seed && element.dataset.fallback) {
608
                apiImages.push(element);
609
              }
610
              const childApiImages = element.querySelectorAll ? element.querySelectorAll('img[data-seed][data-fallback]') : [];
611
              childApiImages.forEach(function(img) {
612
                if (!apiImages.includes(img)) {
613
                  apiImages.push(img);
614
                }
615
              });
616

617
              apiImages.forEach(function(img) {
618
                showLoadingIndicator(img);
619
                if (img.getAttribute('data-need-check-fallback') === 'true') {
620
                  checkAndUseFallbackForFailedApis();
621
                  img.removeAttribute('data-need-check-fallback');
622
                }
623
                if (img.complete && img.naturalWidth > 0 && img.naturalHeight > 0) {
624
                  hideLoadingIndicator(img);
625
                  showWatermark(img);
626
                } else {
627
                  img.addEventListener('loadstart', function() {
628
                    showLoadingIndicator(img);
629
                  }, { once: true });
630
                  img.addEventListener('load', function() {
631
                    if (img.naturalWidth > 0 && img.naturalHeight > 0) {
632
                      hideLoadingIndicator(img);
633
                      showWatermark(img);
634
                    }
635
                  }, { once: true });
636
                  img.addEventListener('error', function() {
637
                    setTimeout(function() {
638
                      hideLoadingIndicator(img);
639
                    }, 500);
640
                  }, { once: true });
641
                }
642
              });
643
            }
644
          });
645
        });
646
      });
647

648
      if (document.body) {
649
        observer.observe(document.body, { childList: true, subtree: true });
650
      } else {
651
        document.addEventListener('DOMContentLoaded', function() {
652
          observer.observe(document.body, { childList: true, subtree: true });
653
        });
654
      }
655
    }
656

657
    function initializeImages() {
658
      if (isPageRefresh()) {
659
        clearApiFailureCache();
660
      } else {
661
        checkAndUseFallbackForFailedApis();
662
      }
663
      optimizePreviewImages();
664

665
      const allApiImages = document.querySelectorAll('img[data-seed][data-fallback]');
666
      allApiImages.forEach(function(img) {
667
        showLoadingIndicator(img);
668
        img.addEventListener('loadstart', function() {
669
          showLoadingIndicator(img);
670
        }, { once: true });
671

672
        if (img.complete && img.naturalWidth > 0 && img.naturalHeight > 0) {
673
          hideLoadingIndicator(img);
674
          showWatermark(img);
675
        } else {
676
          img.addEventListener('load', function() {
677
            if (img.naturalWidth > 0 && img.naturalHeight > 0) {
678
              hideLoadingIndicator(img);
679
              showWatermark(img);
680
            }
681
          }, { once: true });
682
          img.addEventListener('error', function() {
683
            setTimeout(function() {
684
              hideLoadingIndicator(img);
685
            }, 500);
686
          }, { once: true });
687
        }
688
      });
689

690
      setupObserver();
691
    }
692

693
    if (document.readyState === 'loading') {
694
      document.addEventListener('DOMContentLoaded', initializeImages);
695
    } else {
696
      initializeImages();
697
    }
698

699
    // 监听页面可见性变化（从其他页面返回时重新检查）
700
    document.addEventListener('visibilitychange', function() {
701
      if (!document.hidden) {
702
        if (!isPageRefresh()) {
703
          setTimeout(checkAndUseFallbackForFailedApis, 100);
704
        }
705
      }
706
    });
707

708
    // 监听popstate事件（浏览器前进/后退）
709
    window.addEventListener('popstate', function() {
710
      try {
711
        sessionStorage.setItem('random_cover_image_navigation_type', 'back_forward');
712
        sessionStorage.setItem('random_cover_image_last_init_time', Date.now().toString());
713
      } catch (e) {
714
        // 忽略错误
715
      }
716
      setTimeout(function() {
717
        checkAndUseFallbackForFailedApis();
718
      }, 50);
719
    });
720
  })();
721
</script>

展开收起

修改src\components\PostCard.astro封面内容#

src\components\PostCard.astro展开收起

1
---
2
import type { CollectionEntry } from "astro:content";
3
import path from "node:path";
4
import { Icon } from "astro-icon/components";
5
import RandomCoverImage from "@/components/misc/RandomCoverImage.astro";
6
import { processCoverImageSync } from "@/utils/image-utils";
7
import { statsConfig, umamiConfig } from "../config";
8
import I18nKey from "../i18n/i18nKey";
9
import { i18n } from "../i18n/translation";
10
import { getDir } from "../utils/url-utils";
11
import ImageWrapper from "./misc/ImageWrapper.astro";
12
import PostMetadata from "./PostMeta.astro";
29 collapsed lines
13

14
interface Props {
15
  class?: string;
16
  entry: CollectionEntry<"posts">;
17
  title: string;
18
  url: string;
19
  published: Date;
20
  updated?: Date;
21
  tags: string[];
22
  category: string | null;
23
  image: string;
24
  description: string;
25
  draft: boolean;
26
  style: string;
27
  pinned?: boolean;
28
}
29
const {
30
  entry,
31
  title,
32
  url,
33
  published,
34
  updated,
35
  tags,
36
  category,
37
  image,
38
  description,
39
  style,
40
  pinned,
41
} = Astro.props;
42
const className = Astro.props.class;
43

44
//const hasCover = image !== undefined && image !== null && image !== "";
45
// 处理随机图：如果image为"api"，则从配置的API获取随机图
46
const processedImage = processCoverImageSync(image, entry.slug);
47
const hasCover =
48
  processedImage !== undefined &&
49
  processedImage !== null &&
50
  processedImage !== "";
51

52
const coverWidth = "28%";
53

54
const { remarkPluginFrontmatter } = await entry.render();
55
---
43 collapsed lines
56
<div class:list={["card-base flex flex-col-reverse md:flex-col w-full rounded-[var(--radius-large)] overflow-hidden relative", className]} style={style}>
57
    <div class:list={["pl-6 md:pl-9 pr-6 md:pr-2 pt-6 md:pt-7 pb-6 relative", {"w-full md:w-[calc(100%_-_52px_-_12px)]": !hasCover, "w-full md:w-[calc(100%_-_var(--coverWidth)_-_12px)]": hasCover}]}>
58
        {pinned && <div class="absolute top-2 right-2 text-[var(--primary)] flex items-center gap-1">
59
           <Icon name="simple-icons:pinboard" class="w-5 h-5" />
60
            <span class="text-sm hidden md:inline">{i18n(I18nKey.pinned)}</span>
61
        </div>}
62
        <a href={url}
63
           class="transition group w-full block font-bold mb-3 text-3xl text-90
64
        hover:text-[var(--primary)] dark:hover:text-[var(--primary)]
65
        active:text-[var(--title-active)] dark:active:text-[var(--title-active)]
66
        before:w-1 before:h-5 before:rounded-md before:bg-[var(--primary)]
67
        before:absolute before:top-[35px] before:left-[18px] before:hidden md:before:block
68
        ">
69
            {title}
70
            <Icon class="inline text-[2rem] text-[var(--primary)] md:hidden translate-y-0.5 absolute" name="material-symbols:chevron-right-rounded" ></Icon>
71
            <Icon class="text-[var(--primary)] text-[2rem] transition hidden md:inline absolute translate-y-0.5 opacity-0 group-hover:opacity-100 -translate-x-1 group-hover:translate-x-0" name="material-symbols:chevron-right-rounded"></Icon>
72
        </a>
73

74
        <!-- metadata -->
75
        <PostMetadata published={published} updated={updated} tags={tags} category={category} hideTagsForMobile={true} hideUpdateDate={true} class="mb-4"></PostMetadata>
76

77
        <!-- description -->
78
        <div class:list={["transition text-75 mb-3.5 pr-4", {"line-clamp-2 md:line-clamp-1": !description}]}>
79
            { description || remarkPluginFrontmatter.excerpt }
80
        </div>
81

82
        <!-- word count and read time and page views  -->
83
        <div class="text-sm text-black/30 dark:text-white/30 flex gap-4 transition">
84
            <div>
85
                {remarkPluginFrontmatter.words} {" " + i18n(remarkPluginFrontmatter.words === 1 ? I18nKey.wordCount : I18nKey.wordsCount)}
86
            </div>
87
            <div>|</div>
88
            <div>
89
                {remarkPluginFrontmatter.minutes} {" " + i18n(remarkPluginFrontmatter.minutes === 1 ? I18nKey.minuteCount : I18nKey.minutesCount)}
90
            </div>
91
            <div>|</div>
92
            <div>
93
                <span class="text-50 text-sm font-medium" id={`page-views-${entry.slug}`}>{statsConfig.loadingText}</span>
94
            </div>
95
        </div>
96

97
    </div>
98

99
    {hasCover && <a href={url} aria-label={title}
100
                    class:list={["group",
101
                        "max-h-[20vh] md:max-h-none mx-4 mt-4 -mb-2 md:mb-0 md:mx-0 md:mt-0",
102
                        "md:w-[var(--coverWidth)] relative md:absolute md:top-3 md:bottom-3 md:right-3 rounded-xl overflow-hidden active:scale-95"
103
                    ]} >
104
        <div class="absolute pointer-events-none z-10 w-full h-full group-hover:bg-black/30 group-active:bg-black/50 transition"></div>
105
        <div class="absolute pointer-events-none z-20 w-full h-full flex items-center justify-center ">
106
            <Icon name="material-symbols:chevron-right-rounded"
107
                  class="transition opacity-0 group-hover:opacity-100 scale-50 group-hover:scale-100 text-white text-5xl">
108
            </Icon>
109
        </div>
110
        {/* <ImageWrapper src={image} basePath={path.join("content/posts/", getDir(entry.id))} alt="Cover Image of the Post"
111
                  class="w-full h-full">
112
        </ImageWrapper> */}
113
        <RandomCoverImage
114
          src={processedImage}
115
          basePath={path.join("content/posts/", getDir(entry.id))}
116
          alt="Cover Image of the Post"
117
          class="w-full h-full"
118
          seed={entry.slug}
119
          preview={true}
120
        />
121

122
    </a>}
123

124
    {!hasCover &&
125
        <a href={url} aria-label={title} class="!hidden md:!flex btn-regular w-[3.25rem]
126
         absolute right-3 top-3 bottom-3 rounded-xl bg-[var(--enter-btn-bg)]
127
         hover:bg-[var(--enter-btn-bg-hover)] active:bg-[var(--enter-btn-bg-active)] active:scale-95
128
        ">
75 collapsed lines
129
            <Icon name="material-symbols:chevron-right-rounded"
130
                  class="transition text-[var(--primary)] text-4xl mx-auto">
131
            </Icon>
132
        </a>
133
    }
134
</div>
135
<div class="transition border-t-[1px] border-dashed mx-6 border-black/10 dark:border-white/[0.15] last:border-t-0 md:hidden"></div>
136
<script define:vars={{ entry, umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
137
    // 客户端统计文案生成函数
138
    function generateStatsText(pageViews, visits) {
139
        return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
140
    }
141

142
    // 获取文章浏览量统计
143
    async function fetchPostCardViews(slug) {
144
        if (!umamiConfig.enable) {
145
            return;
146
        }
147

148
        try {
149
            // 调用全局工具获取 Umami 分享数据
150
            const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
151

152
            // 第二步：获取统计数据
153
            const currentTimestamp = Date.now();
154
            const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;
155

156
            const statsResponse = await fetch(statsUrl, {
157
                headers: {
158
                    'x-umami-share-token': token
159
                }
160
            });
161

162
            if (statsResponse.status === 401) {
163
                clearUmamiShareCache();
164
                return await fetchPostCardViews(slug);
165
            }
166

167
            if (!statsResponse.ok) {
168
                throw new Error('获取统计数据失败');
169
            }
170

171
            const statsData = await statsResponse.json();
172
            const pageViews = statsData.pageviews || 0;
173
            const visits = statsData.visits || 0;
174

175
            const displayElement = document.getElementById(`page-views-${slug}`);
176
             if (displayElement) {
177
                 displayElement.textContent = generateStatsText(pageViews, visits);
178
             }
179
        } catch (error) {
180
            console.error('Error fetching page views for', slug, ':', error);
181
            const displayElement = document.getElementById(`page-views-${slug}`);
182
            if (displayElement) {
183
                displayElement.textContent = unavailableText;
184
            }
185
        }
186
    }
187

188
    // 页面加载完成后获取统计数据
189
    function initPostCardStats() {
190
        const slug = entry.slug;
191
        if (slug) {
192
            fetchPostCardViews(slug);
193
        }
194
    }
195

196
    if (document.readyState === 'loading') {
197
        document.addEventListener('DOMContentLoaded', initPostCardStats);
198
    } else {
199
        initPostCardStats();
200
    }
201
</script>
202
<style define:vars={{coverWidth}}>
203
</style>

展开收起

修改src\pages\posts[…slug].astro图片显示#

src\pages\posts[...slug].astro展开收起

1
---
8 collapsed lines
2
import path from "node:path";
3
import Giscus from "@components/misc/Giscus.astro";
4
import License from "@components/misc/License.astro";
5
import Markdown from "@components/misc/Markdown.astro";
6
import I18nKey from "@i18n/i18nKey";
7
import { i18n } from "@i18n/translation";
8
import MainGridLayout from "@layouts/MainGridLayout.astro";
9
import { getSortedPosts } from "@utils/content-utils";
10
import { getDir, getPostUrlBySlug } from "@utils/url-utils";
11
import { Icon } from "astro-icon/components";
12
import { licenseConfig } from "src/config";
13
import { processCoverImageSync } from "@/utils/image-utils";
14
import ImageWrapper from "../../components/misc/ImageWrapper.astro";
15
import PostMetadata from "../../components/PostMeta.astro";
16
import { profileConfig, siteConfig } from "../../config";
17
import { formatDateToYYYYMMDD } from "../../utils/date-utils";
18
export async function getStaticPaths() {
19
  const blogEntries = await getSortedPosts();
20
  return blogEntries.map((entry) => ({
6 collapsed lines
21
    params: { slug: entry.slug },
22
    props: { entry },
23
  }));
24
}
25

26
const { entry } = Astro.props;
27
const { Content, headings } = await entry.render();
28

29
const { remarkPluginFrontmatter } = await entry.render();
30

31
// 处理随机图：如果image为"api"，则从配置的API获取随机图
32
const processedImage = processCoverImageSync(entry.data.image, entry.slug);
33

34
const jsonLd = {
35
  "@context": "https://schema.org",
13 collapsed lines
36
  "@type": "BlogPosting",
37
  headline: entry.data.title,
38
  description: entry.data.description || entry.data.title,
39
  keywords: entry.data.tags,
40
  author: {
41
    "@type": "Person",
42
    name: profileConfig.name,
43
    url: Astro.site,
44
  },
45
  datePublished: formatDateToYYYYMMDD(entry.data.published),
46
  inLanguage: entry.data.lang
47
    ? entry.data.lang.replace("_", "-")
48
    : siteConfig.lang.replace("_", "-"),
49
  // TODO include cover image here
50
};
51
---
52
<MainGridLayout banner={processedImage} title={entry.data.title} description={entry.data.description} lang={entry.data.lang} setOGTypeArticle={true} headings={headings} series={entry.data.series}>
53
    <script is:inline slot="head" type="application/ld+json" set:html={JSON.stringify(jsonLd)}></script>
54
    <div class="flex w-full rounded-[var(--radius-large)] overflow-hidden relative mb-4">
55
        <div id="post-container" class:list={["card-base z-10 px-6 md:px-9 pt-6 pb-4 relative w-full ",
41 collapsed lines
56
            {}
57
        ]}>
58
            <!-- word count and reading time -->
59
            <div class="flex flex-row text-black/30 dark:text-white/30 gap-5 mb-3 transition onload-animation">
60
                <div class="flex flex-row items-center">
61
                    <div class="transition h-6 w-6 rounded-md bg-black/5 dark:bg-white/10 text-black/50 dark:text-white/50 flex items-center justify-center mr-2">
62
                        <Icon name="material-symbols:notes-rounded"></Icon>
63
                    </div>
64
                    <div class="text-sm">{remarkPluginFrontmatter.words} {" " + i18n(I18nKey.wordsCount)}</div>
65
                </div>
66
                <div class="flex flex-row items-center">
67
                    <div class="transition h-6 w-6 rounded-md bg-black/5 dark:bg-white/10 text-black/50 dark:text-white/50 flex items-center justify-center mr-2">
68
                        <Icon name="material-symbols:schedule-outline-rounded"></Icon>
69
                    </div>
70
                    <div class="text-sm">
71
                        {remarkPluginFrontmatter.minutes} {" " + i18n(remarkPluginFrontmatter.minutes === 1 ? I18nKey.minuteCount : I18nKey.minutesCount)}
72
                    </div>
73
                </div>
74
            </div>
75

76
            <!-- title -->
77
            <div class="relative onload-animation">
78
                <div
79
                    data-pagefind-body data-pagefind-weight="10" data-pagefind-meta="title"
80
                    class="transition w-full block font-bold mb-3
81
                    text-3xl md:text-[2.25rem]/[2.75rem]
82
                    text-black/90 dark:text-white/90
83
                    md:before:w-1 before:h-5 before:rounded-md before:bg-[var(--primary)]
84
                    before:absolute before:top-[0.75rem] before:left-[-1.125rem]
85
                ">
86
                    {entry.data.title}
87
                </div>
88
            </div>
89

90
            <!-- metadata -->
91
            <div class="onload-animation">
92
                <PostMetadata
93
                        class="mb-5"
94
                        published={entry.data.published}
95
                        updated={entry.data.updated}
96
                        tags={entry.data.tags}
97
                        category={entry.data.category}
98
                        slug={entry.slug}
99
                ></PostMetadata>
100
                {!processedImage && <div class="border-[var(--line-divider)] border-dashed border-b-[1px] mb-5"></div>}
101
            </div>
102

103
            <!-- always show cover as long as it has one -->
104

105
            {processedImage &&
106
                <ImageWrapper id="post-cover" src={processedImage} basePath={path.join("content/posts/", getDir(entry.id))} class="mb-8 rounded-xl banner-container onload-animation"/>
107
            }
108

40 collapsed lines
109

110
            <Markdown class="mb-6 markdown-content onload-animation">
111
                <Content />
112
            </Markdown>
113

114
            {licenseConfig.enable && <License title={entry.data.title} slug={entry.slug} pubDate={entry.data.published} class="mb-6 rounded-xl license-container onload-animation"></License>}
115
            <!-- 评论模块 -->
116
            <Giscus
117
            repo="luozhipeng1/fuwari"
118
            repoId="R_kgDOPvEVqw"
119
            category="Announcements"
120
            categoryId="DIC_kwDOPvEVq84CwMEH"
121
            />
122
            <br>
123
        </div>
124
    </div>
125

126
    <div class="flex flex-col md:flex-row justify-between mb-4 gap-4 overflow-hidden w-full">
127
        <a href={entry.data.nextSlug ? getPostUrlBySlug(entry.data.nextSlug) : "#"}
128
           class:list={["w-full font-bold overflow-hidden active:scale-95", {"pointer-events-none": !entry.data.nextSlug}]}>
129
            {entry.data.nextSlug && <div class="btn-card rounded-2xl w-full h-[3.75rem] max-w-full px-4 flex items-center !justify-start gap-4" >
130
                <Icon name="material-symbols:chevron-left-rounded" class="text-[2rem] text-[var(--primary)]" />
131
                <div class="overflow-hidden transition overflow-ellipsis whitespace-nowrap max-w-[calc(100%_-_3rem)] text-black/75 dark:text-white/75">
132
                    {entry.data.nextTitle}
133
                </div>
134
            </div>}
135
        </a>
136

137
        <a href={entry.data.prevSlug ? getPostUrlBySlug(entry.data.prevSlug) : "#"}
138
           class:list={["w-full font-bold overflow-hidden active:scale-95", {"pointer-events-none": !entry.data.prevSlug}]}>
139
            {entry.data.prevSlug && <div class="btn-card rounded-2xl w-full h-[3.75rem] max-w-full px-4 flex items-center !justify-end gap-4">
140
                <div class="overflow-hidden transition overflow-ellipsis whitespace-nowrap max-w-[calc(100%_-_3rem)] text-black/75 dark:text-white/75">
141
                    {entry.data.prevTitle}
142
                </div>
143
                <Icon name="material-symbols:chevron-right-rounded" class="text-[2rem] text-[var(--primary)]" />
144
            </div>}
145
        </a>
146
    </div>
147

148
</MainGridLayout>

展开收起

使用流程 #

配置 API 列表：在 apis 数组中添加可用的随机图 API
设置备用图片：准备一个备用图片，放在 public 目录下
在文章中使用：在文章的 Frontmatter 中添加 image: "api"
系统自动处理：
- 尝试从 API 获取图片
- 显示加载指示器
- 成功后显示图片和水印
- 失败后使用备用图片并更新水印为 “Image API Error”

注意事项#

1. API 可用性#

确保配置的 API 可以正常访问
建议配置多个 API 作为备用
API 返回的应该是直接的图片 URL，而不是 HTML 页面

2. 备用图片准备#

建议使用 WebP 格式，文件更小
备用图片应该放在 public 目录下
路径要正确（相对于 public 目录）

3. 加载指示器#

背景颜色应与加载 GIF 的背景色一致
只对远程 API 图片显示，本地图片不显示
加载 GIF 建议使用透明背景或与页面背景色一致的背景

4. 水印显示#

只在随机 API 图片成功加载时显示配置的水印文字
API 失败时会自动更新为 “Image API Error”
本地图片不显示水印

5. 缓存机制#

失败的 API 会被记录到 localStorage
下次访问同一文章时，会直接使用备用图片（避免重复请求）
F5 刷新会清除失败记录，重新尝试 API

常见问题#

Q: 如何启用随机封面图功能？

A: 在 coverImageConfig.ts 中设置 enable: true，然后在文章的 Frontmatter 中添加 image: "api"。

Q: 如何添加更多的 API？

A: 在 apis 数组中添加 API URL，系统会按顺序尝试：

1
apis: [
2
  "https://api1.com/image",
3
  "https://api2.com/image",
4
  "https://api3.com/image",
5
]

Q: API 全部失败怎么办？

A: 系统会自动使用 fallback 配置的备用图片，水印文字会自动更新为 “Image API Error”。

Q: 如何禁用水印？

A: 设置 watermark.enable: false 即可。

Q: 如何自定义水印位置？

A: 修改 watermark.position 的值，支持 "top-left"、"top-right"、"bottom-left"、"bottom-right"、"center"。

Q: 为什么移动端水印位置不一样？

A: bottom-left 和 bottom-right 在移动端会自动调整到顶部显示，避免水印被裁剪。这是设计特性，不是 bug。

Q: 如何自定义加载 GIF？

A: 在 loading.image 中设置自定义 GIF 路径，并确保 loading.backgroundColor 与 GIF 背景色一致。

Q: 为什么本地图片不显示加载指示器？

A: 加载指示器只对远程 API 图片显示，本地图片加载较快，不需要显示。

Q: 如何清除 API 失败记录？

A: 按 F5 刷新页面会自动清除 localStorage 中的失败记录，重新尝试 API。

Q: 能否只使用一个 API？

A: 可以，但建议配置多个 API 作为备用，提高可用性。

Q: API 需要支持哪些参数？

A: API 应该直接返回图片，支持 GET 请求。不需要任何特殊参数，系统会自动处理图片加载。

Q: 如何测试 API 是否可用？

A: 在浏览器中直接访问 API URL，应该能看到图片。如果可以，说明 API 可用。

公告配置

Fri, 31 Oct 2025 00:00:00 GMT

概述#

公告配置用于在网站顶部显示重要通知、更新信息或欢迎消息。

基础配置#

启用公告功能#

announcementConfig

1
export const announcementConfig: AnnouncementConfig = {
2
  title: "公告", // 公告标题
3
  content: "欢迎来到我的博客！这是一则示例公告。", // 公告内容
4
  closable: true, // 允许用户关闭公告
5
  link: {
6
    enable: true, // 启用链接
7
    text: "了解更多", // 链接文本
8
    url: "/about/", // 链接 URL
9
    external: false, // 内部链接
10
  },
11
};

配置选项详解#

基础设置#

选项	类型	说明	默认值
`title`	`string`	公告标题	`"公告"`
`content`	`string`	公告内容	`"欢迎来到我的博客！这是一则示例公告。"`
`closable`	`boolean`	是否可关闭	`true`

链接设置#

选项	类型	说明	默认值
`link.enable`	`boolean`	是否启用链接	`true`
`link.text`	`string`	链接文本	`"了解更多"`
`link.url`	`string`	链接地址	`"/about/"`
`link.external`	`boolean`	是否外部链接	`false`

使用场景#

1. 欢迎消息#

demo

1
export const announcementConfig: AnnouncementConfig = {
2
  title: "欢迎",
3
  content: "欢迎来到我的个人博客！这里分享技术文章和生活感悟。",
4
  closable: true,
5
  link: {
6
    enable: true,
7
    text: "了解我",
8
    url: "/about/",
9
    external: false,
10
  },
11
};

2. 更新通知#

demo

1
export const announcementConfig: AnnouncementConfig = {
2
  title: "更新通知",
3
  content: "网站已更新到 v2.0 版本，新增了多项功能！",
4
  closable: true,
5
  link: {
6
    enable: true,
7
    text: "查看更新日志",
8
    url: "/changelog/",
9
    external: false,
10
  },
11
};

3. 重要提醒#

demo

1
export const announcementConfig: AnnouncementConfig = {
2
  title: "重要提醒",
3
  content: "网站将于今晚 22:00-24:00 进行维护，期间可能无法访问。",
4
  closable: false, // 重要提醒不可关闭
5
  link: {
6
    enable: false, // 不需要链接
7
    text: "",
8
    url: "",
9
    external: false,
10
  },
11
};

4. 外部链接#

demo

1
export const announcementConfig: AnnouncementConfig = {
2
  title: "新项目发布",
3
  content: "我的新项目已经发布到 GitHub！",
4
  closable: true,
5
  link: {
6
    enable: true,
7
    text: "查看项目",
8
    url: "https://github.com/username/project",
9
    external: true, // 外部链接
10
  },
11
};

样式自定义#

公告组件支持通过 CSS 自定义样式：

demo.css展开收起

1
  /* 公告容器 */
2
    .announcement-container {
3
        background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
4
        color: white;
5
        padding: 1rem;
6
        border-radius: 8px;
7
        margin-bottom: 1rem;
8
        position: relative;
9
    }
10

11
    /* 公告标题 */
12
    .announcement-title {
13
        font-weight: bold;
14
        font-size: 1.1rem;
15
        margin-bottom: 0.5rem;
16
    }
17

18
    /* 公告内容 */
19
    .announcement-content {
20
        line-height: 1.6;
21
        margin-bottom: 1rem;
22
    }
23

24
    /* 关闭按钮 */
25
    .announcement-close {
26
        position: absolute;
27
        top: 0.5rem;
28
        right: 0.5rem;
29
        background: none;
30
        border: none;
31
        color: white;
32
        cursor: pointer;
33
        font-size: 1.2rem;
34
        width: auto;
35
        height: auto;
36
        padding: 0;
37
    }
38

39
    /* 链接样式 */
40
    .announcement-link {
41
        color: #ffd700;
42
        text-decoration: underline;
43
        font-weight: 500;
44
        background: rgba(255, 255, 255, 0.1);
45
        padding: 0.25rem 0.75rem;
46
        border-radius: 4px;
47
        transition: background 0.2s ease;
48
    }
49

50
    .announcement-link:hover {
51
        background: rgba(255, 255, 255, 0.2);
52
    }

展开收起

新建代码#

src/config.ts#

src/config.ts

1
export const announcementConfig: AnnouncementConfig = {
2
  title: "公告", // 公告标题
3
  content: "欢迎来到我的博客！迅雷APP搜索：【鹏摇星海】，即可获取网盘所有内容", // 公告内容
4
  icon: "fa6-solid:bullhorn", // 公告图标
5
  type: "success", // 公告类型：info, warning, success, error
6
  closable: false, // 允许用户关闭公告
7
  link: {
8
    enable: false, // 启用链接
9
    text: "", // 链接文本
10
    url: "", // 链接 URL
11
    external: false, // 内部链接
12
  },
13
};

src\types\config.ts#

src\types\config.ts

1
export type AnnouncementConfig = {
2
  title?: string; // 公告栏标题
3
  content: string; // 公告栏内容
4
  icon?: string; // 公告栏图标
5
  type?: "info" | "warning" | "success" | "error"; // 公告类型
6
  closable?: boolean; // 是否可关闭
7
  link?: {
8
    enable: boolean; // 是否启用链接
9
    text: string; // 链接文字
10
    url: string; // 链接地址
11
    external?: boolean; // 是否外部链接
12
  };
13
};

src\i18n\i18nKey.ts#

src/i18n/i18nKey.ts展开收起

1
enum I18nKey {
2
  // ....省略
3
  publishedAt = "publishedAt",
4
  license = "license",
5

6
  pinned = "pinned",
7

8
  series = "series",
9

10
  friends = "friends",
11

12
  donate = "donate",
13

14
  announcement = "announcement",
15
  announcementClose = "announcementClose",
16
}
17

18
export default I18nKey;

展开收起

各国语言#

各国语言展开收起

1
  // en.ts
2
  [Key.announcement]: "Announcement",
3
  [Key.announcementClose]: "Close",
4

5
  // es.ts
6
    [Key.announcement]: "Anuncio",
7
  [Key.announcementClose]: "Cerrar",
8

9
    // id.ts
10
    [Key.announcement]: "Pengumuman",
11
  [Key.announcementClose]: "Tutup",
12

13
    // ja.ts
14
    [Key.announcement]: "お知らせ",
15
  [Key.announcementClose]: "閉じる",
16

17
    // ko.ts
18
    [Key.announcement]: "공지사항",
19
  [Key.announcementClose]: "닫기",
20

21
    // th.ts
22
    [Key.announcement]: "ประกาศ",
23
  [Key.announcementClose]: "ปิด",
24

25
    // tr.ts
26
    [Key.announcement]: "Duyuru",
27
  [Key.announcementClose]: "Kapat",
28

29
    // vi.ts
30
    [Key.announcement]: "Thông báo",
31
  [Key.announcementClose]: "Đóng",
32

33
    // zh_CN.ts
34
    [Key.announcement]: "公告",
35
  [Key.announcementClose]: "关闭",
36

37
     // zh_TW.ts
38
     [Key.announcement]: "公告",
39
   [Key.announcementClose]: "關閉",

展开收起

src\components\widget\Announcement.astro#

src\components\widget\Announcement.astro展开收起

1
---
2
import { Icon } from "astro-icon/components";
3
import { announcementConfig } from "@/config/announcementConfig";
4
import I18nKey from "@/i18n/i18nKey";
5
import { i18n } from "@/i18n/translation";
6
import WidgetLayout from "./WidgetLayout.astro";
7

8
const config = announcementConfig;
9

10
interface Props {
11
  class?: string;
12
  style?: string;
13
}
14
const className = Astro.props.class;
15
const style = Astro.props.style;
16

17
// 根据公告类型确定样式类
18
const getTypeClass = (type: string | undefined) => {
19
  switch (type) {
20
    case "info":
21
      return "bg-blue-100 border-blue-500 text-blue-700 dark:bg-blue-900 dark:border-blue-300 dark:text-blue-200";
22
    case "warning":
23
      return "bg-yellow-100 border-yellow-500 text-yellow-700 dark:bg-yellow-900 dark:border-yellow-300 dark:text-yellow-200";
24
    case "success":
25
      return "bg-green-100 border-green-500 text-green-700 dark:bg-green-900 dark:border-green-300 dark:text-green-200";
26
    case "error":
27
      return "bg-red-100 border-red-500 text-red-700 dark:bg-red-900 dark:border-red-300 dark:text-red-200";
28
    default:
29
      return "bg-gray-100 border-gray-500 text-gray-700 dark:bg-gray-800 dark:border-gray-300 dark:text-gray-200";
30
  }
31
};
32
---
33

34

35
<WidgetLayout
36
    name={config.title || i18n(I18nKey.announcement)}
37
    id="announcement"
38
    class={className}
39
    style={style}
40
>
41
    <div class={`announcement-container border-l-4 p-4 rounded ${getTypeClass(config.type)}`}>
42
        <!-- 公告栏图标和标题 -->
43
        <div class="flex items-center gap-2 mb-2">
44
            {config.icon && <Icon name={config.icon} class="text-lg" />}
45
            {config.title && <h3 class="font-bold">{config.title}</h3>}
46
        </div>
47

48
        <!-- 公告栏内容 -->
49
        <div class="announcement-content mb-3">
50
            {config.content}
51
        </div>
52

53
        <!-- 可选链接和关闭按钮 -->
54
        <div class="flex items-center justify-between gap-3">
55
            <div>
56
                {
57
                    config.link && config.link.enable !== false && (
58
                        <a
59
                            href={config.link.url}
60
                            target={config.link.external ? "_blank" : "_self"}
61
                            rel={
62
                                config.link.external
63
                                    ? "noopener noreferrer"
64
                                    : undefined
65
                            }
66
                            class="announcement-link font-medium underline"
67
                        >
68
                            {config.link.text}
69
                        </a>
70
                    )
71
                }
72
            </div>
73

74
            {
75
                config.closable && (
76
                    <button
77
                        class="announcement-close"
78
                        onclick="closeAnnouncement()"
79
                        aria-label={i18n(I18nKey.announcementClose)}
80
                    >
81
                        <Icon name="fa6-solid:xmark" class="text-sm" />
82
                    </button>
83
                )
84
            }
85
        </div>
86
    </div>
87
</WidgetLayout>
88

89
<script>
90
    // 扩展 Window 接口以包含 closeAnnouncement 方法
91
    declare global {
92
        interface Window {
93
            closeAnnouncement: () => void;
94
        }
95
    }
96

97
    function closeAnnouncement() {
98
        // 通过data-id属性找到整个widget-layout元素
99
        const widgetLayout = document.querySelector(
100
            'widget-layout[data-id="announcement"]',
101
        );
102
        if (widgetLayout) {
103
            // 隐藏整个widget-layout元素
104
            (widgetLayout as HTMLElement).style.display = "none";
105
            // 保存关闭状态到localStorage
106
            localStorage.setItem("announcementClosed", "true");
107
        }
108
    }
109

110
    // 页面加载时检查是否已关闭
111
    document.addEventListener("DOMContentLoaded", function () {
112
        const widgetLayout = document.querySelector(
113
            'widget-layout[data-id="announcement"]',
114
        );
115
        if (
116
            widgetLayout &&
117
            localStorage.getItem("announcementClosed") === "true"
118
        ) {
119
            (widgetLayout as HTMLElement).style.display = "none";
120
        }
121
    });
122

123
    // 使公告栏函数全局可用
124
    window.closeAnnouncement = closeAnnouncement;
125
</script>

展开收起

src\components\widget\SideBar.astro#

src\components\widget\SideBar.astro展开收起

1
---
2
import type { MarkdownHeading } from "astro";
3
import Announcement from "./Announcement.astro";
4
import Categories from "./Categories.astro";
5
import Profile from "./Profile.astro";
6
import Series from "./Series.astro";
7
import Tag from "./Tags.astro";
8
import TOC from "./TOC.astro";
9

10
interface Props {
11
  class?: string;
12
  headings?: MarkdownHeading[];
13
  series?: string;
14
}
15

16
const className = Astro.props.class;
17
const headings = Astro.props.headings;
18
const series = Astro.props.series;
19
---
20
<div id="sidebar" class:list={[className, "w-full"]}>
21
    <div class="flex flex-col w-full gap-4 mb-4">
22
        <Profile></Profile>
23
    </div>
24
    <div id="sidebar-sticky" class="transition-all duration-700 flex flex-col w-full gap-4 top-4 sticky top-4">
25
        <div id="series" class="flex flex-col w-full gap-4">
26
            { series && <Series series={ series }></Series> }
27
        </div>
28
        <Categories class="onload-animation" style="animation-delay: 150ms"></Categories>
29
        <Announcement></Announcement>
30
        <Tag class="onload-animation" style="animation-delay: 200ms"></Tag>
31
    </div>
32
</div>

展开收起

效果演示#

image-20251031212822971

樱花特效配置

Tue, 28 Oct 2025 00:00:00 GMT

概述#

樱花特效配置用于在网站中添加动态的樱花飘落效果，营造浪漫的视觉氛围。

前言#

最近想要添加的功能有点多，我把整个config.ts配置文件拆分为多个模块化文件，创建独立的siteConfig、navBarConfig等模块

基础配置#

sakuraConfig.ts展开收起

1
import type { SakuraConfig } from "../types/config";
2

3
export const sakuraConfig: SakuraConfig = {
4
  enable: true, // 默认关闭樱花特效
5
  type: 'canvas', // 樱花特效类型：'canvas' 或 'css'
6
  sakuraNum: 30, // 樱花数量
7
  limitTimes: -1, // 樱花越界限制次数，-1为无限循环
8
  size: {
9
    min: 0.4, // 樱花最小尺寸倍数
10
    max: 1.2, // 樱花最大尺寸倍数
11
  },
12
  opacity: {
13
    min: 0.5, // 樱花最小不透明度
14
    max: 1, // 樱花最大不透明度
15
  },
16
  speed: {
17
    horizontal: {
18
      min: -1.7, // 水平移动速度最小值
19
      max: -1.2, // 水平移动速度最大值
20
    },
21
    vertical: {
22
      min: 1.5, // 垂直移动速度最小值
23
      max: 2.2, // 垂直移动速度最大值
24
    },
25
    rotation: 0.03, // 旋转速度
26
    fadeSpeed: 0.03, // 消失速度，不应大于最小不透明度
27
  },
28
  zIndex: 100, // 层级，确保樱花在合适的层级显示
29
};

展开收起

基础设置#

选项	类型	说明	默认值
`enable`	`boolean`	是否启用樱花特效	`true`
`type`	`‘canvas'	'css’`	樱花特效类型：‘canvas’ 或 ‘css
`sakuraNum`	`number`	樱花数量	`21`
`limitTimes`	`number`	越界限制次数，-1为无限	`-1`

尺寸设置#

选项	类型	说明	默认值
`size.min`	`number`	樱花最小尺寸倍数	`0.5`
`size.max`	`number`	樱花最大尺寸倍数	`1.1`

透明度设置#

选项	类型	说明	默认值
`opacity.min`	`number`	樱花最小不透明度	`0.3`
`opacity.max`	`number`	樱花最大不透明度	`0.9`

速度设置#

选项	类型	说明	默认值
`speed.horizontal.min`	`number`	水平移动速度最小值	`-1.7`
`speed.horizontal.max`	`number`	水平移动速度最大值	`-1.2`
`speed.vertical.min`	`number`	垂直移动速度最小值	`1.5`
`speed.vertical.max`	`number`	垂直移动速度最大值	`2.2`
`speed.rotation`	`number`	旋转速度	`0.03`
`speed.fadeSpeed`	`number`	消失速度，不应大于最小不透明度	`0.03`

层级设置#

选项	类型	说明	默认值
`zIndex`	`number`	樱花层级	`100`

使用场景#

1. 浪漫主题网站#

SakuraConfig展开收起

1
export const sakuraConfig: SakuraConfig = {
2
  enable: true,
3
  type: 'canvas',
4
  sakuraNum: 30, // 更多樱花
5
  limitTimes: -1,
6
  size: {
7
    min: 0.8,
8
    max: 1.5, // 更大的樱花
9
  },
10
  opacity: {
11
    min: 0.4,
12
    max: 0.95, // 更高的透明度
13
  },
14
  speed: {
15
    horizontal: {
16
      min: -2.0,
17
      max: -1.0, // 更慢的飘落
18
    },
19
    vertical: {
20
      min: 1.0,
21
      max: 1.8,
22
    },
23
    rotation: 0.02, // 更慢的旋转
24
    fadeSpeed: 0.02, // 更慢的消失
25
  },
26
  zIndex: 100,
27
};

展开收起

2. 简约风格#

SakuraConfig展开收起

1
export const sakuraConfig: SakuraConfig = {
2
  enable: true,
3
  type: 'canvas',
4
  sakuraNum: 10, // 少量樱花
5
  limitTimes: -1,
6
  size: {
7
    min: 0.3,
8
    max: 0.8, // 较小的樱花
9
  },
10
  opacity: {
11
    min: 0.2,
12
    max: 0.7, // 较低的透明度
13
  },
14
  speed: {
15
    horizontal: {
16
      min: -1.0,
17
      max: -0.5,
18
    },
19
    vertical: {
20
      min: 2.0,
21
      max: 3.0, // 较快的飘落
22
    },
23
    rotation: 0.05,
24
    fadeSpeed: 0.05, // 较快的消失
25
  },
26
  zIndex: 100,
27
};

展开收起

3. 节日主题#

SakuraConfig展开收起

1
export const sakuraConfig: SakuraConfig = {
2
  enable: true,
3
  type: 'canvas',
4
  sakuraNum: 50, // 大量樱花营造节日氛围
5
  limitTimes: -1,
6
  size: {
7
    min: 0.4,
8
    max: 1.2,
9
  },
10
  opacity: {
11
    min: 0.5,
12
    max: 1.0, // 完全不透明
13
  },
14
  speed: {
15
    horizontal: {
16
      min: -2.5,
17
      max: -1.5,
18
    },
19
    vertical: {
20
      min: 1.2,
21
      max: 2.5,
22
    },
23
    rotation: 0.04,
24
    fadeSpeed: 0.04,
25
  },
26
  zIndex: 100,
27
};

展开收起

性能优化#

根据设备调整#

SakuraConfig展开收起

1
// 根据设备性能调整樱花数量
2
const isMobile = typeof window !== 'undefined' && window.innerWidth < 768;
3

4
export const sakuraConfig: SakuraConfig = {
5
  enable: true,
6
  type: 'canvas',
7
  sakuraNum: isMobile ? 10 : 21, // 移动端减少樱花数量
8
  size: {
9
    min: 0.5,
10
    max: 1.1,
11
  },
12
  opacity: {
13
    min: 0.3,
14
    max: 0.9,
15
  },
16
  speed: {
17
    horizontal: { min: -1.7, max: -1.2 },
18
    vertical: { min: 1.5, max: 2.2 },
19
    rotation: 0.03,
20
    fadeSpeed: 0.03,
21
  },
22
  zIndex: 100,
23
};

展开收起

条件启用#

SakuraConfig

1
// 只在特定页面启用
2
export const sakuraConfig: SakuraConfig = {
3
  enable: process.env.NODE_ENV === 'production', // 只在生产环境启用
4
  // ... 其他配置
5
};

新建代码#

src\types\config.ts#

src\types\config.ts展开收起

1
// ....其他配置
2

3
export type SakuraConfig = {
4
  enable: boolean; // 是否启用樱花特效
5
  type?: 'canvas' | 'css'; // 樱花特效类型：'canvas' 或 'css
6
  sakuraNum: number; // 樱花数量，默认21
7
  limitTimes: number; // 樱花越界限制次数，-1为无限循环
8
  size: {
9
    min: number; // 樱花最小尺寸倍数
10
    max: number; // 樱花最大尺寸倍数
11
  };
12
  opacity: {
13
    min: number; // 樱花最小不透明度
14
    max: number; // 樱花最大不透明度
15
  };
16
  speed: {
17
    horizontal: {
18
    min: number; // 水平移动速度最小值
19
    max: number; // 水平移动速度最大值
20
    };
21
    vertical: {
22
    min: number; // 垂直移动速度最小值
23
    max: number; // 垂直移动速度最大值
24
    };
25
    rotation: number; // 旋转速度
26
    fadeSpeed: number; // 消失速度，不应大于最小不透明度
27
  };
28
  zIndex: number; // 层级，确保樱花在合适的层级显示
29
  };

展开收起

src\components\effects\SakuraEffect.astro#

新建effects 文件夹，创建SakuraEffect.astro文件

src\components\effects\SakuraEffect.astro展开收起

1
---
2
import { sakuraConfig } from "@/config";
3

4
const config = sakuraConfig;
5
---
6

7
{sakuraConfig?.enable && sakuraConfig.type === 'canvas' && (
8
  <script define:vars={{ sakuraConfig: config }}>
9
    // 樱花对象类
10
    class Sakura {
11
      constructor(x, y, s, r, a, fn, idx, img, limitArray, config) {
12
        this.x = x;
13
        this.y = y;
14
        this.s = s;
15
        this.r = r;
16
        this.a = a;
17
        this.fn = fn;
18
        this.idx = idx;
19
        this.img = img;
20
        this.limitArray = limitArray;
21
        this.config = config;
22
      }
23

24
      draw(cxt) {
25
        cxt.save();
26
        cxt.translate(this.x, this.y);
27
        cxt.rotate(this.r);
28
        cxt.globalAlpha = this.a;
29
        cxt.drawImage(this.img, 0, 0, 40 * this.s, 40 * this.s);
30
        cxt.restore();
31
      }
32

33
      update() {
34
        this.x = this.fn.x(this.x, this.y);
35
        this.y = this.fn.y(this.y, this.y);
36
        this.r = this.fn.r(this.r);
37
        this.a = this.fn.a(this.a);
38
        // 如果樱花越界，重新调整位置
39
        if (
40
          this.x > window.innerWidth ||
41
          this.x < 0 ||
42
          this.y > window.innerHeight ||
43
          this.y < 0 ||
44
          this.a <= 0
45
        ) {
46
          // 如果樱花不做限制
47
          if (this.limitArray[this.idx] === -1) {
48
            this.resetPosition();
49
          }
50
          // 否则樱花有限制
51
          else {
52
            if (this.limitArray[this.idx] > 0) {
53
              this.resetPosition();
54
              this.limitArray[this.idx]--;
55
            }
56
          }
57
        }
58
      }
59

60
      resetPosition() {
61
        this.r = getRandom('fnr', this.config);
62
        if (Math.random() > 0.4) {
63
          this.x = getRandom('x', this.config);
64
          this.y = 0;
65
          this.s = getRandom('s', this.config);
66
          this.r = getRandom('r', this.config);
67
          this.a = getRandom('a', this.config);
68
        } else {
69
          this.x = window.innerWidth;
70
          this.y = getRandom('y', this.config);
71
          this.s = getRandom('s', this.config);
72
          this.r = getRandom('r', this.config);
73
          this.a = getRandom('a', this.config);
74
        }
75
      }
76
    }
77

78
    // 樱花列表类
79
    class SakuraList {
80
      constructor() {
81
        this.list = [];
82
      }
83

84
      push(sakura) {
85
        this.list.push(sakura);
86
      }
87

88
      update() {
89
        for (let i = 0, len = this.list.length; i < len; i++) {
90
          this.list[i].update();
91
        }
92
      }
93

94
      draw(cxt) {
95
        for (let i = 0, len = this.list.length; i < len; i++) {
96
          this.list[i].draw(cxt);
97
        }
98
      }
99

100
      get(i) {
101
        return this.list[i];
102
      }
103

104
      size() {
105
        return this.list.length;
106
      }
107
    }
108

109
    // 获取随机值的函数
110
    function getRandom(option, config) {
111
      let ret;
112
      let random;
113

114
      switch (option) {
115
        case 'x':
116
          ret = Math.random() * window.innerWidth;
117
          break;
118
        case 'y':
119
          ret = Math.random() * window.innerHeight;
120
          break;
121
        case 's':
122
          ret = config.size.min + Math.random() * (config.size.max - config.size.min);
123
          break;
124
        case 'r':
125
          ret = Math.random() * 6;
126
          break;
127
        case 'a':
128
          ret = config.opacity.min + Math.random() * (config.opacity.max - config.opacity.min);
129
          break;
130
        case 'fnx':
131
          random = config.speed.horizontal.min + Math.random() * (config.speed.horizontal.max - config.speed.horizontal.min);
132
          ret = function (x, y) {
133
            return x + random;
134
          };
135
          break;
136
        case 'fny':
137
          random = config.speed.vertical.min + Math.random() * (config.speed.vertical.max - config.speed.vertical.min);
138
          ret = function (x, y) {
139
            return y + random;
140
          };
141
          break;
142
        case 'fnr':
143
          ret = function (r) {
144
            return r + config.speed.rotation;
145
          };
146
          break;
147
        case 'fna':
148
          ret = function (alpha) {
149
            return alpha - config.speed.fadeSpeed * 0.01;
150
          };
151
          break;
152
      }
153
      return ret;
154
    }
155

156
    // 樱花管理器类
157
    class SakuraManager {
158
      constructor(config) {
159
        this.config = config;
160
        this.canvas = null;
161
        this.ctx = null;
162
        this.sakuraList = null;
163
        this.animationId = null;
164
        this.img = null;
165
        this.isRunning = false;
166
      }
167

168
      // 初始化樱花特效
169
      async init() {
170
        if (!this.config.enable || this.isRunning) {
171
          return;
172
        }
173

174
        // 创建图片对象
175
        this.img = new Image();
176
        this.img.src = '/donate/sakura.png'; // 使用樱花图片
177

178
        // 等待图片加载完成
179
        await new Promise((resolve, reject) => {
180
          if (this.img) {
181
            this.img.onload = () => resolve();
182
            this.img.onerror = () => reject(new Error('Failed to load sakura image'));
183
          }
184
        });
185

186
        this.createCanvas();
187
        this.createSakuraList();
188
        this.startAnimation();
189
        this.isRunning = true;
190
      }
191

192
      // 创建画布
193
      createCanvas() {
194
        this.canvas = document.createElement('canvas');
195
        this.canvas.height = window.innerHeight;
196
        this.canvas.width = window.innerWidth;
197
        this.canvas.setAttribute('style', `position: fixed; left: 0; top: 0; pointer-events: none; z-index: ${this.config.zIndex};`);
198
        this.canvas.setAttribute('id', 'canvas_sakura');
199
        document.body.appendChild(this.canvas);
200
        this.ctx = this.canvas.getContext('2d');
201

202
        // 监听窗口大小变化
203
        window.addEventListener('resize', this.handleResize.bind(this));
204
      }
205

206
      // 创建樱花列表
207
      createSakuraList() {
208
        if (!this.img || !this.ctx) return;
209

210
        this.sakuraList = new SakuraList();
211
        const limitArray = new Array(this.config.sakuraNum).fill(this.config.limitTimes);
212

213
        for (let i = 0; i < this.config.sakuraNum; i++) {
214
          const randomX = getRandom('x', this.config);
215
          const randomY = getRandom('y', this.config);
216
          const randomS = getRandom('s', this.config);
217
          const randomR = getRandom('r', this.config);
218
          const randomA = getRandom('a', this.config);
219
          const randomFnx = getRandom('fnx', this.config);
220
          const randomFny = getRandom('fny', this.config);
221
          const randomFnR = getRandom('fnr', this.config);
222
          const randomFnA = getRandom('fna', this.config);
223

224
          const sakura = new Sakura(
225
            randomX,
226
            randomY,
227
            randomS,
228
            randomR,
229
            randomA,
230
            {
231
              x: randomFnx,
232
              y: randomFny,
233
              r: randomFnR,
234
              a: randomFnA,
235
            },
236
            i,
237
            this.img,
238
            limitArray,
239
            this.config
240
          );
241

242
          sakura.draw(this.ctx);
243
          this.sakuraList.push(sakura);
244
        }
245
      }
246

247
      // 开始动画
248
      startAnimation() {
249
        if (!this.ctx || !this.canvas || !this.sakuraList) return;
250

251
        const animate = () => {
252
          if (!this.ctx || !this.canvas || !this.sakuraList) return;
253

254
          this.ctx.clearRect(0, 0, this.canvas.width, this.canvas.height);
255
          this.sakuraList.update();
256
          this.sakuraList.draw(this.ctx);
257
          this.animationId = requestAnimationFrame(animate);
258
        };
259

260
        this.animationId = requestAnimationFrame(animate);
261
      }
262

263
      // 处理窗口大小变化
264
      handleResize() {
265
        if (this.canvas) {
266
          this.canvas.width = window.innerWidth;
267
          this.canvas.height = window.innerHeight;
268
        }
269
      }
270

271
      // 停止樱花特效
272
      stop() {
273
        if (this.animationId) {
274
          cancelAnimationFrame(this.animationId);
275
          this.animationId = null;
276
        }
277

278
        if (this.canvas) {
279
          document.body.removeChild(this.canvas);
280
          this.canvas = null;
281
        }
282

283
        window.removeEventListener('resize', this.handleResize.bind(this));
284
        this.isRunning = false;
285
      }
286

287
      // 切换樱花特效
288
      toggle() {
289
        if (this.isRunning) {
290
          this.stop();
291
        } else {
292
          this.init();
293
        }
294
      }
295

296
      // 更新配置
297
      updateConfig(newConfig) {
298
        const wasRunning = this.isRunning;
299
        if (wasRunning) {
300
          this.stop();
301
        }
302
        this.config = newConfig;
303
        if (wasRunning && newConfig.enable) {
304
          this.init();
305
        }
306
      }
307

308
      // 获取运行状态
309
      getIsRunning() {
310
        return this.isRunning;
311
      }
312
    }
313

314
    // 创建全局樱花管理器实例
315
    let globalSakuraManager = null;
316

317
    // 初始化樱花特效
318
    function initSakura(config) {
319
      if (globalSakuraManager) {
320
        globalSakuraManager.updateConfig(config);
321
      } else {
322
        globalSakuraManager = new SakuraManager(config);
323
        if (config.enable) {
324
          globalSakuraManager.init();
325
        }
326
      }
327
    }
328

329
    // 樱花特效初始化
330
    (function() {
331
      // 全局标记，确保樱花特效只初始化一次
332
      if (window.sakuraInitialized) {
333
        return;
334
      }
335

336
      // 初始化樱花特效的函数
337
      const setupSakura = () => {
338
        if (sakuraConfig.enable && !window.sakuraInitialized) {
339
          initSakura(sakuraConfig);
340
          window.sakuraInitialized = true;
341
        }
342
      };
343

344
      // 页面加载完成后初始化樱花特效
345
      if (document.readyState === 'loading') {
346
        document.addEventListener('DOMContentLoaded', setupSakura);
347
      } else {
348
        setupSakura();
349
      }
350
    })();
351
  </script>
352
)}
353

354
{sakuraConfig?.enable && sakuraConfig.type === 'css' && (
355
  <div class="sakura-container">
356
    <script define:vars={{ sakuraConfig: config }}>
357
      function createCSSSakura() {
358
        const container = document.querySelector('.sakura-container');
359
        const sakuraCount = sakuraConfig?.sakuraNum || 50;
360

361
        for (let i = 0; i < sakuraCount; i++) {
362
          const sakura = document.createElement('div');
363
          sakura.classList.add('sakura');
364

365
          // 随机大小
366
          const sizes = ['small', 'medium', 'large'];
367
          const size = sizes[Math.floor(Math.random() * sizes.length)];
368
          sakura.classList.add(size);
369

370
          // 随机方向
371
          const directions = ['left', 'center', 'right'];
372
          const direction = directions[Math.floor(Math.random() * directions.length)];
373
          sakura.classList.add(direction);
374

375
          // 随机位置
376
          const startX = Math.random() * 100;
377
          sakura.style.left = `${startX}vw`;
378

379
          // 随机延迟
380
          const delay = Math.random() * 5;
381
          sakura.style.animationDelay = `${delay}s`;
382

383
          // 随机动画时长
384
          const fallDuration = 10 + Math.random() * 20;
385
          const swingDuration = 2 + Math.random() * 3;
386
          sakura.style.setProperty('--fall-duration', `${fallDuration}s`);
387
          sakura.style.setProperty('--swing-duration', `${swingDuration}s`);
388

389
          container.appendChild(sakura);
390
        }
391
      }
392

393
      // 页面加载完成后创建樱花
394
      if (document.readyState === 'loading') {
395
        document.addEventListener('DOMContentLoaded', createCSSSakura);
396
      } else {
397
        createCSSSakura();
398
      }
399
    </script>
400
  </div>
401
)}
402

403

404
<style scoped>
405
/* 樱花容器 */
406
.sakura-container {
407
  position: fixed;
408
  top: 0;
409
  left: 0;
410
  width: 100%;
411
  height: 100%;
412
  pointer-events: none;
413
  z-index: 100;
414
  overflow: hidden;
415
}
416

417
/* 单个樱花 */
418
.sakura {
419
  position: absolute;
420
  width: 10px;
421
  height: 10px;
422
  background: radial-gradient(circle, #ffb3ba 0%, #ff9a9e 100%);
423
  border-radius: 50% 0 50% 0;
424
  opacity: 0;
425
  box-shadow: 0 0 2px rgba(255, 188, 198, 0.8);
426
  filter: blur(0.5px);
427
  top: -20px;
428
  animation:
429
    sakura-fall linear infinite,
430
    sakura-swing ease-in-out infinite,
431
    sakura-fade var(--fade-duration, 5s) forwards;
432
}
433

434
/* 樱花飘落动画 */
435
@keyframes sakura-fall {
436
  to {
437
    transform: translateY(100vh) rotate(360deg);
438
  }
439
}
440

441
/* 樱花摆动动画 */
442
@keyframes sakura-swing {
443
  0%, 100% {
444
    transform: translateX(0) translateY(0) rotate(0deg);
445
  }
446
  25% {
447
    transform: translateX(5px) translateY(calc(25vh)) rotate(90deg);
448
  }
449
  50% {
450
    transform: translateX(0) translateY(calc(50vh)) rotate(180deg);
451
  }
452
  75% {
453
    transform: translateX(-5px) translateY(calc(75vh)) rotate(270deg);
454
  }
455
}
456

457
/* 樱花淡入淡出效果 */
458
@keyframes sakura-fade {
459
  0% {
460
    opacity: 0;
461
  }
462
  10% {
463
    opacity: 0.8;
464
  }
465
  90% {
466
    opacity: 0.6;
467
  }
468
  100% {
469
    opacity: 0;
470
  }
471
}
472

473
/* 不同大小的樱花 */
474
.sakura.small {
475
  width: 6px;
476
  height: 6px;
477
  --fall-duration: 15s;
478
  --swing-duration: 3s;
479
  --fade-duration: 15s;
480
}
481

482
.sakura.medium {
483
  width: 10px;
484
  height: 10px;
485
  --fall-duration: 20s;
486
  --swing-duration: 4s;
487
  --fade-duration: 20s;
488
}
489

490
.sakura.large {
491
  width: 14px;
492
  height: 14px;
493
  --fall-duration: 25s;
494
  --swing-duration: 5s;
495
  --fade-duration: 25s;
496
}
497

498
/* 粉色樱花 */
499
.sakura.pink {
500
  background: radial-gradient(circle, #ffb3ba 0%, #ff9a9e 100%);
501
}
502

503
/* 白色樱花 */
504
.sakura.white {
505
  background: radial-gradient(circle, #ffffff 0%, #f0f0f0 100%);
506
}
507

508
/* 渐变樱花 */
509
.sakura.gradient {
510
  background: linear-gradient(45deg, #ff9a9e 0%, #fecfef 50%, #fecfef 100%);
511
}
512

513
/* 樱花飘落方向 */
514
.sakura.left {
515
  animation:
516
    sakura-fall-left var(--fall-duration, 15s) linear infinite,
517
    sakura-swing var(--swing-duration, 3s) ease-in-out infinite,
518
    sakura-fade var(--fade-duration, 15s) forwards;
519
}
520

521
.sakura.right {
522
  animation:
523
    sakura-fall-right var(--fall-duration, 15s) linear infinite,
524
    sakura-swing var(--swing-duration, 4s) ease-in-out infinite,
525
    sakura-fade var(--fade-duration, 15s) forwards;
526
}
527

528
.sakura.center {
529
  animation:
530
    sakura-fall var(--fall-duration, 15s) linear infinite,
531
    sakura-swing var(--swing-duration, 2s) ease-in-out infinite,
532
    sakura-fade var(--fade-duration, 15s) forwards;
533
}
534

535
/* 樱花飘落动画 - 左侧 */
536
@keyframes sakura-fall-left {
537
  to {
538
    transform: translateY(100vh) translateX(-20vw) rotate(360deg);
539
  }
540
}
541

542
/* 樱花飘落动画 - 右侧 */
543
@keyframes sakura-fall-right {
544
  to {
545
    transform: translateY(100vh) translateX(20vw) rotate(360deg);
546
  }
547
}
548

549
/* 樱花飘落动画 - 中间 */
550
@keyframes sakura-fall-center {
551
  to {
552
    transform: translateY(100vh) rotate(360deg);
553
  }
554
}
555
</style>

展开收起

自定义sakura.css#

这个css写的不是很好，我个人没有用css样式生成的樱花，而是采用canvas图片绘画而成的

src\styles\sakura.css展开收起

1
/* 樱花容器 */
2
.sakura-container {
3
  position: fixed;
4
  top: 0;
5
  left: 0;
6
  width: 100%;
7
  height: 100%;
8
  pointer-events: none;
9
  z-index: 100;
10
  overflow: hidden;
11
}
12

13
/* 单个樱花 */
14
.sakura {
15
  position: absolute;
16
  width: 10px;
17
  height: 10px;
18
  background: radial-gradient(circle, #ffb3ba 0%, #ff9a9e 100%);
19
  border-radius: 50% 0 50% 0;
20
  opacity: 0;
21
  box-shadow: 0 0 2px rgba(255, 188, 198, 0.8);
22
  filter: blur(0.5px);
23
  top: -20px;
24
  animation:
25
    sakura-fall linear infinite,
26
    sakura-swing ease-in-out infinite,
27
    sakura-fade var(--fade-duration, 5s) forwards;
28
}
29

30
/* 樱花飘落动画 */
31
@keyframes sakura-fall {
32
  to {
33
    transform: translateY(100vh) rotate(360deg);
34
  }
35
}
36

37
/* 樱花摆动动画 */
38
@keyframes sakura-swing {
39
  0%, 100% {
40
    transform: translateX(0) translateY(0) rotate(0deg);
41
  }
42
  25% {
43
    transform: translateX(5px) translateY(calc(25vh)) rotate(90deg);
44
  }
45
  50% {
46
    transform: translateX(0) translateY(calc(50vh)) rotate(180deg);
47
  }
48
  75% {
49
    transform: translateX(-5px) translateY(calc(75vh)) rotate(270deg);
50
  }
51
}
52

53
/* 樱花淡入淡出效果 */
54
@keyframes sakura-fade {
55
  0% {
56
    opacity: 0;
57
  }
58
  10% {
59
    opacity: 0.8;
60
  }
61
  90% {
62
    opacity: 0.6;
63
  }
64
  100% {
65
    opacity: 0;
66
  }
67
}
68

69
/* 不同大小的樱花 */
70
.sakura.small {
71
  width: 6px;
72
  height: 6px;
73
  --fall-duration: 15s;
74
  --swing-duration: 3s;
75
  --fade-duration: 15s;
76
}
77

78
.sakura.medium {
79
  width: 10px;
80
  height: 10px;
81
  --fall-duration: 20s;
82
  --swing-duration: 4s;
83
  --fade-duration: 20s;
84
}
85

86
.sakura.large {
87
  width: 14px;
88
  height: 14px;
89
  --fall-duration: 25s;
90
  --swing-duration: 5s;
91
  --fade-duration: 25s;
92
}
93

94
/* 粉色樱花 */
95
.sakura.pink {
96
  background: radial-gradient(circle, #ffb3ba 0%, #ff9a9e 100%);
97
}
98

99
/* 白色樱花 */
100
.sakura.white {
101
  background: radial-gradient(circle, #ffffff 0%, #f0f0f0 100%);
102
}
103

104
/* 渐变樱花 */
105
.sakura.gradient {
106
  background: linear-gradient(45deg, #ff9a9e 0%, #fecfef 50%, #fecfef 100%);
107
}
108

109
/* 樱花飘落方向 */
110
.sakura.left {
111
  animation:
112
    sakura-fall-left var(--fall-duration, 15s) linear infinite,
113
    sakura-swing var(--swing-duration, 3s) ease-in-out infinite,
114
    sakura-fade var(--fade-duration, 15s) forwards;
115
}
116

117
.sakura.right {
118
  animation:
119
    sakura-fall-right var(--fall-duration, 15s) linear infinite,
120
    sakura-swing var(--swing-duration, 4s) ease-in-out infinite,
121
    sakura-fade var(--fade-duration, 15s) forwards;
122
}
123

124
.sakura.center {
125
  animation:
126
    sakura-fall var(--fall-duration, 15s) linear infinite,
127
    sakura-swing var(--swing-duration, 2s) ease-in-out infinite,
128
    sakura-fade var(--fade-duration, 15s) forwards;
129
}
130

131
/* 樱花飘落动画 - 左侧 */
132
@keyframes sakura-fall-left {
133
  to {
134
    transform: translateY(100vh) translateX(-20vw) rotate(360deg);
135
  }
136
}
137

138
/* 樱花飘落动画 - 右侧 */
139
@keyframes sakura-fall-right {
140
  to {
141
    transform: translateY(100vh) translateX(20vw) rotate(360deg);
142
  }
143
}
144

145
/* 樱花飘落动画 - 中间 */
146
@keyframes sakura-fall-center {
147
  to {
148
    transform: translateY(100vh) rotate(360deg);
149
  }
150
}

展开收起

SakuraEffect.astro组件在src\layouts\MainGridLayout.astro引用

src\layouts\MainGridLayout.astro展开收起

1
import BackToTop from "@components/control/BackToTop.astro";
2
import Footer from "@components/Footer.astro";
3
import Navbar from "@components/Navbar.astro";
4
import SideBar from "@components/widget/SideBar.astro";
5
import SakuraEffect from "@/components/effects/SakuraEffect.astro";
6
import type { MarkdownHeading } from "astro";
7
import { Icon } from "astro-icon/components";
8
import ImageWrapper from "../components/misc/ImageWrapper.astro";
9
import TOC from "../components/widget/TOC.astro";
10
import { siteConfig } from "../config";
11
import {
12
  BANNER_HEIGHT,
13
  BANNER_HEIGHT_EXTEND,
14
  MAIN_PANEL_OVERLAPS_BANNER_HEIGHT,
15
} from "../constants/constants";
16
import Layout from "./Layout.astro";
17

18
// ....省略
19

20

21

22
<Layout title={title} banner={banner} description={description} lang={lang} setOGTypeArticle={setOGTypeArticle}>
23
<!-- 樱花特效 -->
24
<SakuraEffect/>
25
<!-- Navbar -->
26

27
// ....省略

展开收起

注意事项#

性能影响：樱花特效会消耗一定的 CPU 和内存资源
用户体验：过多的樱花可能影响用户阅读内容
设备兼容：在低性能设备上可能影响页面流畅度
可访问性：动画可能对某些用户造成不适
透明度设置：opacity.min 和 opacity.max 控制樱花的透明度范围
消失速度：fadeSpeed 不应大于 opacity.min，否则樱花可能不会完全消失

常见问题#

Q: 如何禁用樱花特效？ A: 将 enable 设置为 false

Q: 樱花数量多少合适？ A: 建议在 10-30 个之间，根据网站性能调整

Q: 如何调整樱花飘落速度？ A: 修改 speed 配置中的数值，数值越大速度越快

Q: 樱花会影响页面性能吗？ A: 会有一定影响，建议在低性能设备上减少樱花数量

Q: 如何自定义樱花颜色？ A: 通过 CSS 覆盖 .sakura 类的背景样式

Q: 樱花在哪些页面显示？ A: 默认在所有页面显示，可以通过代码控制特定页面显示

Q: 如何调整樱花层级？ A: 修改 zIndex 值，确保樱花在合适的层级显示

Q: 如何调整樱花透明度？ A: 修改 opacity.min 和 opacity.max 值，控制樱花的透明度范围

Q: 樱花消失太快怎么办？ A: 减小 fadeSpeed 的值，让樱花消失得更慢

Q: 樱花不消失怎么办？ A: 确保 fadeSpeed 不大于 opacity.min，否则樱花可能不会完全消失

增加 FUwari 代码块双主题

Fri, 24 Oct 2025 00:00:00 GMT

这篇文章来记录一下美化博客的代码。代码模块跟随主题变动而变化

修改代码#

astro.config.mjs#

astro.config.mjs展开收起

1
// 。。。 修改此处代码
2
expressiveCode({
3
      // themes: [expressiveCodeConfig.theme, expressiveCodeConfig.theme],
4
      themes: expressiveCodeConfig.themes,
5
      plugins: [
6
        pluginCollapsibleSections(),
7
        pluginLineNumbers(),
8
        pluginLanguageBadge(),
9
        pluginCustomCopyButton(),
10
      ],
11
      defaultProps: {
12
        wrap: true,
13
        overridesByLang: {
14
          shellsession: {
15
            showLineNumbers: false,
16
          },
17
        },
18
      },
19
      // styleOverrides: {
20
      //   codeBackground: "var(--codeblock-bg)",
21
      //   borderRadius: "0.75rem",
22
      //   borderColor: "none",
23
      //   codeFontSize: "0.875rem",
24
      //   codeFontFamily:
25
      //     "'JetBrains Mono Variable', ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace",
26
      //   codeLineHeight: "1.5rem",
27
      //   frames: {
28
      //     editorBackground: "var(--codeblock-bg)",
29
      //     terminalBackground: "var(--codeblock-bg)",
30
      //     terminalTitlebarBackground: "var(--codeblock-topbar-bg)",
31
      //     editorTabBarBackground: "var(--codeblock-topbar-bg)",
32
      //     editorActiveTabBackground: "none",
33
      //     editorActiveTabIndicatorBottomColor: "var(--primary)",
34
      //     editorActiveTabIndicatorTopColor: "none",
35
      //     editorTabBarBorderBottomColor: "var(--codeblock-topbar-bg)",
36
      //     terminalTitlebarBorderBottomColor: "none",
37
      //   },
38
      //   textMarkers: {
39
      //     delHue: 0,
40
      //     insHue: 180,
41
      //     markHue: 250,
42
      //   },
43
      // },
44
      // frames: {
45
      //   showCopyToClipboardButton: false,
46
      // },
47
    }),
48

49
    // 。。。 修改此处代码

展开收起

src/types/config.ts#

src\types\config.ts

1
// 。。。下滑至最下面
2
export type ExpressiveCodeConfig = {
3
  theme: string[];
4
};

src/config.ts#

src\config.ts

1
// 。。。下滑至最下面
2

3
export const expressiveCodeConfig: ExpressiveCodeConfig = {
4
  // Note: Some styles (such as background color) are being overridden, see the astro.config.mjs file.
5
  // Please select a dark theme, as this blog theme currently only supports dark background color
6
  theme: ["github-light", "github-dark"],
7
};

src/utils/setting-utils.ts#

src\utils\setting-utils.ts

1
  // Set the theme for Expressive Code
2
  const isDarkMode = document.documentElement.classList.contains("dark");
3
  document.documentElement.setAttribute(
4
    "data-theme",
5
    expressiveCodeConfig.theme[Number(isDarkMode)],
6
  );

演示效果#

晚上#

image-20251024135212536

白天#

image-20251024135350807

FUwari 二级导航

Fri, 24 Oct 2025 00:00:00 GMT

之前被 Fuwari 主题的简约清新风格打动，便将博客主题换成了它。但在使用过程中发现，原生 Fuwari 主题仅支持单级导航，这对我的博客来说并不够用 —— 我的博客内容分为生活记录、技术分享、旅行攻略等几大类，每类下又有细分内容，比如技术分享里包含基础编程、软件使用技巧等，单级导航会让访客难以快速定位内容。因此，为 Fuwari 主题添加二级导航，支持二级菜单配置，桌面端悬停展开，移动端点击切换，如今这项功能已成功实现，在此分享具体过程。

二级菜单配置#

在导航栏配置中支持二级菜单，可以创建下拉菜单结构：

配置说明：

name - 菜单显示名称
url - 链接地址（父级菜单建议使用 #）
children - 子菜单数组
external - 是否为外部链接

功能特性：

桌面端：鼠标悬停展开二级菜单
移动端：点击切换二级菜单显示/隐藏
支持无限层级嵌套
自动适应内容宽度

src\config.ts展开收起

1
export const navBarConfig: NavBarConfig = {
2
  links: [
3
    LinkPreset.Home,
4
    LinkPreset.Archive,
5
    LinkPreset.About,
6
    LinkPreset.Series,
7
    LinkPreset.Friends,
8
    LinkPreset.Donate,
9
    {
10
      name: "其他", // 标题
11
      url: "#", // 内部链接不应包含基本路径，因为它是自动添加的
12
      children: [
13
        {
14
          name: "访客统计",
15
          url: "https://cloud.umami.is/share/i6f3UwPY4n0w1LJa/pengxing.dpdns.org", // 内部链接不应包含基本路径，因为它是自动添加的
16
          external: true, //显示外部链接图标，并将在新选项卡中打开
17
        },
18
        {
19
          name: "网盘资源",
20
          url: "https://docs.qq.com/aio/DYmZYVGpFVGxOS3NE", // 内部链接不应包含基本路径，因为它是自动添加的
21
          external: true, //显示外部链接图标，并将在新选项卡中打开
22
        },
23
      ],
24
    },
25
  ],
26
};

展开收起

修改代码#

src/components/Navbar.astro#

src\components\Navbar.astro展开收起


22 collapsed lines
1
---
2
import { Icon } from "astro-icon/components";
3
import { navBarConfig, siteConfig } from "../config";
4
import { LinkPresets } from "../constants/link-presets";
5
import { LinkPreset, type NavBarLink } from "../types/config";
6
import { url } from "../utils/url-utils";
7
import LightDarkSwitch from "./LightDarkSwitch.svelte";
8
import Search from "./Search.svelte";
9
import DisplaySettings from "./widget/DisplaySettings.svelte";
10
import NavMenuPanel from "./widget/NavMenuPanel.astro";
11

12
const className = Astro.props.class;
13

14
let links: NavBarLink[] = navBarConfig.links.map(
15
  (item: NavBarLink | LinkPreset): NavBarLink => {
16
    if (typeof item === "number") {
17
      return LinkPresets[item];
18
    }
19
    return item;
20
  },
21
);
22
---
23
<div id="navbar" class="z-50 onload-animation">
24
    <div class="absolute h-8 left-0 right-0 -top-8 bg-[var(--card-bg)] transition"></div> <!-- used for onload animation -->
25
    <div class:list={[
26
        className,
27
        "card-base !overflow-visible max-w-[var(--page-width)] h-[4.5rem] !rounded-t-none mx-auto flex items-center justify-between px-4"]}>
28
        <a href={url('/')} class="btn-plain scale-animation rounded-lg h-[3.25rem] px-5 font-bold active:scale-95">
29
            <div class="flex flex-row text-[var(--primary)] items-center text-md">
30
                <Icon name="material-symbols:home-outline-rounded" class="text-[1.75rem] mb-1 mr-2" />
31
                {siteConfig.title}
32
            </div>
33
        </a>
34
        <div class="hidden md:flex">
35
            {links.map((l) => {
36
                // return <a aria-label={l.name} href={l.external ? l.url : url(l.url)} target={l.external ? "_blank" : null}
37
                //           class="btn-plain scale-animation rounded-lg h-11 font-bold px-5 active:scale-95"
38
                // >
39
                //     <div class="flex items-center">
40
                //         {l.name}
41
                //         {l.external && <Icon name="fa6-solid:arrow-up-right-from-square" class="text-[0.875rem] transition -translate-y-[1px] ml-1 text-black/[0.2] dark:text-white/[0.2]"></Icon>}
42
                //     </div>
43
                // </a>;
44
                if (l.children && l.children.length > 0) {
45
                    // 有子菜单的情况
46
                    return <div class="relative group">
47
                        <button class="btn-plain scale-animation rounded-lg h-11 font-bold px-5 active:scale-95 flex items-center">
48
                            {l.name}
49
                            <Icon name="material-symbols:keyboard-arrow-down-rounded" class="text-[1.25rem] ml-1 transition-transform group-hover:rotate-180"></Icon>
50
                        </button>
51
                        <div class="absolute top-full left-0 mt-2 min-w-max bg-[var(--card-bg)] border border-[var(--line-divider)] rounded-lg shadow-lg opacity-0 invisible group-hover:opacity-100 group-hover:visible transition-all duration-200 z-50 whitespace-nowrap">
52
                            {l.children.map((child) => (
53
                                 <a href={child.external ? child.url : url(child.url)} target={child.external ? "_blank" : null}
54
                                    class="btn-plain scale-animation block px-4 py-3 text-sm font-bold hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)] first:rounded-t-lg last:rounded-b-lg transition-all duration-200 active:scale-95 mx-1 my-0.5 rounded-lg">
55
                                     <div class="flex items-center justify-between">
56
                                         {child.name}
57
                                         {child.external && <Icon name="fa6-solid:arrow-up-right-from-square" class="text-[0.75rem] text-black/[0.2] dark:text-white/[0.2]"></Icon>}
58
                                     </div>
59
                                 </a>
60
                             ))}
61
                        </div>
62
                    </div>;
63
                } else {
64
                    // 没有子菜单的情况
65
                    return <a aria-label={l.name} href={l.external ? l.url : url(l.url)} target={l.external ? "_blank" : null}
66
                              class="btn-plain scale-animation rounded-lg h-11 font-bold px-5 active:scale-95"
67
                    >
68
                        <div class="flex items-center">
69
                            {l.name}
70
                            {l.external && <Icon name="fa6-solid:arrow-up-right-from-square" class="text-[0.875rem] transition -translate-y-[1px] ml-1 text-black/[0.2] dark:text-white/[0.2]"></Icon>}
71
                        </div>
72
                    </a>;
73
                }
74

75
            })}
76
        </div>
77
        <div class="flex">
95 collapsed lines
78
            <!--<SearchPanel client:load>-->
79
            <Search client:only="svelte"></Search>
80
            {!siteConfig.themeColor.fixed && (
81
                    <button aria-label="Display Settings" class="btn-plain scale-animation rounded-lg h-11 w-11 active:scale-90" id="display-settings-switch">
82
                        <Icon name="material-symbols:palette-outline" class="text-[1.25rem]"></Icon>
83
                    </button>
84
            )}
85
            <LightDarkSwitch client:only="svelte"></LightDarkSwitch>
86
            <button aria-label="Menu" name="Nav Menu" class="btn-plain scale-animation rounded-lg w-11 h-11 active:scale-90 md:!hidden" id="nav-menu-switch">
87
                <Icon name="material-symbols:menu-rounded" class="text-[1.25rem]"></Icon>
88
            </button>
89
        </div>
90
        <NavMenuPanel links={links}></NavMenuPanel>
91
        <DisplaySettings client:only="svelte"></DisplaySettings>
92
    </div>
93
</div>
94

95
<script>
96
function switchTheme() {
97
    if (localStorage.theme === 'dark') {
98
        document.documentElement.classList.remove('dark');
99
        localStorage.theme = 'light';
100
    } else {
101
        document.documentElement.classList.add('dark');
102
        localStorage.theme = 'dark';
103
    }
104
}
105

106
function loadButtonScript() {
107
    let switchBtn = document.getElementById("scheme-switch");
108
    if (switchBtn) {
109
        switchBtn.onclick = function () {
110
            switchTheme()
111
        };
112
    }
113

114
    let settingBtn = document.getElementById("display-settings-switch");
115
    if (settingBtn) {
116
        settingBtn.onclick = function () {
117
            let settingPanel = document.getElementById("display-setting");
118
            if (settingPanel) {
119
                settingPanel.classList.toggle("float-panel-closed");
120
            }
121
        };
122
    }
123

124
    let menuBtn = document.getElementById("nav-menu-switch");
125
    if (menuBtn) {
126
        menuBtn.onclick = function () {
127
            let menuPanel = document.getElementById("nav-menu-panel");
128
            if (menuPanel) {
129
                menuPanel.classList.toggle("float-panel-closed");
130
            }
131
        };
132
    }
133
}
134

135
loadButtonScript();
136
</script>
137

138
{import.meta.env.PROD && <script is:inline define:vars={{scriptUrl: url('/pagefind/pagefind.js')}}>
139
async function loadPagefind() {
140
    try {
141
        const response = await fetch(scriptUrl, { method: 'HEAD' });
142
        if (!response.ok) {
143
            throw new Error(`Pagefind script not found: ${response.status}`);
144
        }
145

146
        const pagefind = await import(scriptUrl);
147

148
        await pagefind.options({
149
            excerptLength: 20
150
        });
151

152
        window.pagefind = pagefind;
153

154
        document.dispatchEvent(new CustomEvent('pagefindready'));
155
        console.log('Pagefind loaded and initialized successfully, event dispatched.');
156
    } catch (error) {
157
        console.error('Failed to load Pagefind:', error);
158
        window.pagefind = {
159
            search: () => Promise.resolve({ results: [] }),
160
            options: () => Promise.resolve(),
161
        };
162
        document.dispatchEvent(new CustomEvent('pagefindloaderror'));
163
        console.log('Pagefind load error, event dispatched.');
164
    }
165
}
166

167
if (document.readyState === 'loading') {
168
    document.addEventListener('DOMContentLoaded', loadPagefind);
169
} else {
170
    loadPagefind();
171
}
172
</script>}

展开收起

src/components/widget/NavMenuPanel.astro#

src\components\widget\NavMenuPanel.astro展开收起


11 collapsed lines
1
---
2
import { Icon } from "astro-icon/components";
3
import { type NavBarLink } from "../../types/config";
4
import { url } from "../../utils/url-utils";
5

6
interface Props {
7
  links: NavBarLink[];
8
}
9

10
const links = Astro.props.links;
11
---
12
<div id="nav-menu-panel" class:list={["float-panel float-panel-closed absolute transition-all fixed right-4 px-2 py-2"]}>
13
    <!-- {links.map((link) => (
14
        <a href={link.external ? link.url : url(link.url)} class="group flex justify-between items-center py-2 pl-3 pr-1 rounded-lg gap-8
15
            hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)] transition
16
        "
17
           target={link.external ? "_blank" : null}
18
        >
19
            <div class="transition text-black/75 dark:text-white/75 font-bold group-hover:text-[var(--primary)] group-active:text-[var(--primary)]">
20
                {link.name}
21
            </div>
22
            {!link.external && <Icon name="material-symbols:chevron-right-rounded"
23
                  class="transition text-[1.25rem] text-[var(--primary)]"
24
            >
25
            </Icon>}
26
            {link.external && <Icon name="fa6-solid:arrow-up-right-from-square"
27
                  class="transition text-[0.75rem] text-black/25 dark:text-white/25 -translate-x-1"
28
            >
29
            </Icon>}
30
        </a>
31
    ))} -->
32
    {links.map((link) => {
33
        if (link.children && link.children.length > 0) {
34
            // 有子菜单的情况
35
            return (
36
                <div class="nav-menu-item-with-children">
37
                    <button class="group flex justify-between items-center py-2 pl-3 pr-1 rounded-lg gap-8 w-full
38
                        hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)] transition
39
                        nav-submenu-toggle"
40
                    >
41
                        <div class="transition text-black/75 dark:text-white/75 font-bold group-hover:text-[var(--primary)] group-active:text-[var(--primary)]">
42
                            {link.name}
43
                        </div>
44
                        <Icon name="material-symbols:keyboard-arrow-down-rounded"
45
                              class="transition text-[1.25rem] text-[var(--primary)] nav-submenu-arrow"
46
                        >
47
                        </Icon>
48
                    </button>
49
                    <div class="nav-submenu pl-4 max-h-0 overflow-hidden transition-all duration-200">
50
                        {link.children.map((child) => (
51
                            <a href={child.external ? child.url : url(child.url)} class="group flex justify-between items-center py-2 pl-3 pr-1 rounded-lg gap-8
52
                                hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)] transition
53
                            "
54
                               target={child.external ? "_blank" : null}
55
                            >
56
                                <div class="transition text-black/60 dark:text-white/60 text-sm group-hover:text-[var(--primary)] group-active:text-[var(--primary)]">
57
                                    {child.name}
58
                                </div>
59
                                {!child.external && <Icon name="material-symbols:chevron-right-rounded"
60
                                      class="transition text-[1rem] text-[var(--primary)]"
61
                                >
62
                                </Icon>}
63
                                {child.external && <Icon name="fa6-solid:arrow-up-right-from-square"
64
                                      class="transition text-[0.65rem] text-black/25 dark:text-white/25 -translate-x-1"
65
                                >
66
                                </Icon>}
67
                            </a>
68
                        ))}
69
                    </div>
70
                </div>
71
            );
72
        } else {
73
            // 没有子菜单的情况
74
            return (
75
                <a href={link.external ? link.url : url(link.url)} class="group flex justify-between items-center py-2 pl-3 pr-1 rounded-lg gap-8
76
                    hover:bg-[var(--btn-plain-bg-hover)] active:bg-[var(--btn-plain-bg-active)] transition
77
                "
78
                   target={link.external ? "_blank" : null}
79
                >
80
                    <div class="transition text-black/75 dark:text-white/75 font-bold group-hover:text-[var(--primary)] group-active:text-[var(--primary)]">
81
                        {link.name}
82
                    </div>
83
                    {!link.external && <Icon name="material-symbols:chevron-right-rounded"
84
                          class="transition text-[1.25rem] text-[var(--primary)]"
85
                    >
86
                    </Icon>}
87
                    {link.external && <Icon name="fa6-solid:arrow-up-right-from-square"
88
                          class="transition text-[0.75rem] text-black/25 dark:text-white/25 -translate-x-1"
89
                    >
90
                    </Icon>}
91
                </a>
92
            );
93
        }
94
    })}
95
</div>
96

97
<script>
98
    // 移动端二级菜单展开/收起功能
99
    document.addEventListener('DOMContentLoaded', function() {
100
        const submenuToggles = document.querySelectorAll('.nav-submenu-toggle');
101

102
        submenuToggles.forEach(toggle => {
103
            toggle.addEventListener('click', function(this: HTMLElement) {
104
                const submenu = this.parentElement?.querySelector('.nav-submenu') as HTMLElement;
105
                const arrow = this.querySelector('.nav-submenu-arrow') as HTMLElement;
106

107
                if (submenu && arrow) {
108
                    const isExpanded = submenu.style.maxHeight && submenu.style.maxHeight !== '0px';
109

110
                    if (isExpanded) {
111
                        submenu.style.maxHeight = '0px';
112
                        arrow.style.transform = 'rotate(0deg)';
113
                    } else {
114
                        submenu.style.maxHeight = submenu.scrollHeight + 'px';
115
                        arrow.style.transform = 'rotate(180deg)';
116
                    }
117
                }
118
            });
119
        });
120
    });
121
</script>

展开收起

src/config.ts#

src\config.ts展开收起


42 collapsed lines
1
import type {
2
  ExpressiveCodeConfig,
3
  LicenseConfig,
4
  NavBarConfig,
5
  ProfileConfig,
6
  SiteConfig,
7
  UmamiConfig,
8
} from "./types/config";
9
import { LinkPreset } from "./types/config";
10

11
export const siteConfig: SiteConfig = {
12
  title: "PengXing's Blog", // 标题
13
  subtitle: "爱你所爱！", // 副标题
14
  lang: "zh_CN", // 'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th' 语言设置
15
  themeColor: {
16
    hue: 250, // 主题色的色调范围从0到360。例如：红色：0，青色：200，蓝色：250，粉色：345
17
    fixed: false, // 是否隐藏主题颜色选择器，访客可见
18
  },
19
  banner: {
20
    enable: true, // 是否启用横幅
21
    src: "assets/images/demo-banner.png", // 横幅图片的路径，相对于 /src 目录，如果路径以 / 开头则相对于 /public 目录，或者完整路径的网络图片
22
    position: "center", // 横幅位置，对应 object-position 属性，只支持 'top', 'center', 'bottom'，默认为 'center'
23
    credit: {
24
      enable: false, // 是否显示横幅图片的版权信息
25
      text: "", // 显示的版权文字
26
      url: "", // （可选）指向原始艺术作品或艺术家页面的 URL 链接
27
    },
28
  },
29
  toc: {
30
    enable: true, // 是否在文章右侧显示目录
31
    depth: 2, // 显示目录的最大标题深度，从 1 到 3
32
  },
33
  favicon: [
34
    // 留空数组以使用默认的 favicon
35
    {
36
      src: "/favicon/favicon.ico", // favicon 的路径，相对于 /public 目录
37
      theme: "light", // （可选）设置为 'light' 或 'dark'，仅当有不同的 favicon 时才设置
38
      sizes: "32x32", // （可选）favicon 的尺寸，仅当有不同尺寸的 favicon 时设置
39
    },
40
  ],
41
};
42

43
export const navBarConfig: NavBarConfig = {
44
  links: [
45
    LinkPreset.Home,
46
    LinkPreset.Archive,
47
    LinkPreset.About,
48
    LinkPreset.Series,
49
    LinkPreset.Friends,
50
    LinkPreset.Donate,
51
    {
52
      name: "其他", // Link text
53
      url: "#", // Internal links should not include the base path, as it is automatically added
54
      children: [
55
        {
56
          name: "访客统计",
57
          url: "https://cloud.umami.is/share/i6f3UwPY4n0w1LJa/pengxing.dpdns.org", // Internal links should not include the base path, as it is automatically added
58
          external: true, // Show an external link icon and will open in a new tab
59
        },
60
        {
61
          name: "网盘资源",
62
          url: "https://docs.qq.com/aio/DYmZYVGpFVGxOS3NE", // Internal links should not include the base path, as it is automatically added
63
          external: true, // Show an external link icon and will open in a new tab
64
        },
65
      ],
66
    },
67
  ],
68
};
69

63 collapsed lines
70
export const profileConfig: ProfileConfig = {
71
  avatar: "assets/images/demo-avatar.png", // 头像路径，相对于 /src 目录，如果路径以 / 开头则相对于 /public 目录
72
  name: "鹏星",
73
  bio: "Love what you love,  all will be well! / 爱你所爱，一切美好！", // 个人简介
74
  links: [
75
    // {
76
    //   name: "Twitter",
77
    //   icon: "fa6-brands:twitter", // Visit https://icones.js.org/ for icon codes
78
    //   // You will need to install the corresponding icon set if it's not already included
79
    //   // `pnpm add @iconify-json/<icon-set-name>`
80
    //   url: "https://twitter.com",
81
    // },
82
    // {
83
    //   name: "Steam",
84
    //   icon: "fa6-brands:steam",
85
    //   url: "https://store.steampowered.com",
86
    // },
87
    // {
88
    //   name: "GitHub",
89
    //   icon: "fa6-brands:github",
90
    //   url: "https://github.com/saicaca/fuwari",
91
    // },
92
    {
93
      name: "QQ频道",
94
      icon: "fa6-brands:qq",
95
      url: "https://pd.qq.com/s/38it5vmzn",
96
    },
97
    {
98
      name: "link3",
99
      icon: "fa6-brands:staylinked",
100
      url: "https://link3.cc/pyxh",
101
    },
102
  ],
103
};
104

105
export const licenseConfig: LicenseConfig = {
106
  enable: true,
107
  name: "CC BY-NC-SA 4.0",
108
  url: "https://creativecommons.org/licenses/by-nc-sa/4.0/",
109
};
110

111
export const expressiveCodeConfig: ExpressiveCodeConfig = {
112
  // Note: Some styles (such as background color) are being overridden, see the astro.config.mjs file.
113
  // Please select a dark theme, as this blog theme currently only supports dark background color
114
  theme: ["github-light", "github-dark"],
115
};
116

117
// 在 config.ts 中配置 Umami 相关信息
118
export const umamiConfig: UmamiConfig = {
119
  enable: true,
120
  baseUrl: "https://cloud.umami.is",
121
  shareId: "i6f3UwPY4n0w1LJa",
122
  timezone: "Asia/Shanghai",
123
};
124

125
export const statsConfig = {
126
  viewsText: "浏览量",
127
  visitsText: "访客",
128
  loadingText: "统计加载中...",
129
  unavailableText: "统计不可用。",
130
  getStatsText: (pageViews: number, visits: number) =>
131
    `${statsConfig.viewsText} ${pageViews} · ${statsConfig.visitsText} ${visits}`,
132
};

展开收起

src/types/config.ts#

src\types\config.ts

1
// 。。。。只需要修改这一处,其他保存不变
2

3
export type NavBarLink = {
4
  name: string;
5
  url: string;
6
  external?: boolean;
7
  children?: NavBarLink[]; // 支持二级菜单
8
};
9

10

11
// 。。。。只需要修改这一处,其他保存不变

演示效果#

image-20251024131530487

Typora免付费激活

Wed, 15 Oct 2025 00:00:00 GMT

进入 Typora 官方中文站

下载并安装，假设你的安装路径为 D:/App/Typora

关闭所有Typora相关进程

用VSCode打开 D:/App/Typora

全局搜索，将

1
e.hasActivated="true"==e.hasActivated

改为

1
e.hasActivated="true"==“true”

打开 Typora，已激活

image-20251015210908934

软件下载#

如果以上方法不行，还可以直接下载网盘中的Typora

下载链接： https://pan.baidu.com/s/1BMExIudcPn0uFCf58ar5wQ?pwd=pyxh

image-20251015211152848

Win10计算机管理中本地用户和组不见了怎么办？

Wed, 15 Oct 2025 00:00:00 GMT

打开计算机管理却发现本地用户和组不见了？要找回它们很简单，只需在Microsoft管理控制台或控制面板添加即可。

有的时候我们想为计算机添加一个新用户，打开计算机管理却发现本地用户和组不见了。那遇到计算机管理没有本地用户和组该怎么办？我们可以通过Microsoft管理控制台或控制面板添加本地用户和组以解决问题。

一、在控制台添加本地用户和组#

本地用户是可以用来在本地登录的账户，不同账户权限有所不同，在计算机中所能使用的功能也会有着不同的限制，而组则是本地用户管理的单元。若遇到Windows 10本地用户和组不见了，你可以在Microsoft管理控制台添加本地用户和组。操作步骤如下：

1. 按键盘上的**“Windows + R”组合键打开运行对话框，然后输入“mmc”,再单击“确定”**打开Microsoft管理控制台。

mmc

2. 进入控制台后，单击窗口左上角的**“文件” > “添加/删除管理单元”**。

添加/删除管理单元

3. 在添加或删除管理员单元窗口左侧的**“可用的管理单元”中找到“本地用户和组”，然后选中“本地用户和组”，再单击中间的“添加”**按钮。

添加

4. 在弹出的选择目标机器窗口中，选择**“本地计算机（运行此控制台的计算机）”，再单击“完成”**即可。

选择目标机器

若你点击**“完成”按钮提示“此管理单元不能用于这一版本的Windows 10”**，则说明你的Windows 10版本可能是家庭版，你可以将版本升级到专业版或采用下面的方法添加用户账户。

此管理单元不能用于这一版本的Windows 10

二、通过控制面板添加用户#

在Microsoft管理控制台添加本地用户和组失败，是因为Windows 10家庭版没有本地用户和组。那Windows 10家庭版没有本地用户和组怎么办？你可以通过控制面板添加用户以解决问题，具体的操作步骤如下：

1. 打开**“控制面板”，在控制面板中单击“用户账户”**。

控制面板

2. 进入**“用户账户”后，再次单击“用户账户”**。

用户账户

3. 在此窗口中，单击**“管理其他账户”**。

管理其他账户

4. 进入**“管理账户”窗口后，再单击“在电脑设置中添加新用户”**。

在电脑设置中添加新用户

5. 然后在**“家庭和其他用户”中，你可以单击“将其他人添加到这台电脑”**以添加新的用户账户。

家庭和其他用户

6. 接着会让你登录Microsoft账户，登录成功后再输入新账户的用户名和密码即可。

用户名和密码

若你遇到打开计算机管理发现本地用户和组不见了，你可以在Microsoft管理控制台中重新添加本地用户和组，或者可以通过控制面板创建新的用户。以上就是本文的全部内容，希望对你有所帮助。

为 Fuwari 添加 Giscus 评论系统

Fri, 03 Oct 2025 00:00:00 GMT

介绍#

Fuwari 作为一款基于 Astro 框架的轻量级静态博客模板，以其简洁的设计和卓越的性能受到开发者青睐。然而，评论功能一直是静态博客的短板，传统评论系统往往需要复杂的后端配置和数据库支持。

本文将详细介绍如何为 Fuwari 静态博客无缝集成 Giscus 评论系统，实现基于 GitHub Discussions 的轻量级、无需数据库的评论解决方案。并实现兼容亮色/暗色主题的自适应效果。

配置#

准备 GitHub 仓库#

首先，我们需要在 GitHub 上创建一个专门用于存储评论的仓库。这个仓库必须是公开的，因为 Giscus 需要通过访问 GitHub 仓库来加载和提交评论。

创建新仓库
- 登录 GitHub，点击右上角 ”+” 按钮
- 选择 “New repository”
- 填写仓库名称（如 fuwari-comments）和其他必要信息
- 确保仓库可见性设置为 Public
启用 Discussions 功能
- 进入仓库的 Settings → Features
- 找到 “Discussions” 选项并勾选
- 点击 “Save changes” 保存
- Discussions 是 GitHub 为项目讨论提供的平台，Giscus 将利用这一功能存储评论

配置 Giscus#

接下来，我们需要配置 Giscus 以将评论与我们的仓库关联起来。

连接仓库
- 前往 https://giscus.app/zh-CN
- 选择语言后在下方填写你的仓库
- 通过检查后 Discussion 将被连接到该仓库
  image-20251003115939818
选择映射关系 推荐选择 pathname，假如你的文章路径为 posts/helloworld，那么只要你保证这个路径不变，评论和页面就永远匹配
image-20251003120040606
选择 Discussion 分类 推荐使用 公告（Announcements） 类型的分类，以确保新 discussion 只能由仓库维护者和 giscus 创建
image-20251003120131231
获取配置信息

完成以上步骤后，记录以下配置信息，稍后将在 Fuwari 中使用：
- 仓库名称
- 仓库 ID
- 分类名称
- 分类 ID

image-20251003120516834

添加到 Fuwari#

创建 Giscus 组件

为了实现在亮色/暗色下都能使 Giscus 完美显示,我们需要在 src/components/misc/ 目录下创建 Giscus.astro 文件，内容如下：

src/components/misc/Giscus.astro展开收起

1
---
2
interface Props {
3
  repo: string;
4
  repoId: string;
5
  category: string;
6
  categoryId: string;
7
  mapping?: string;
8
  reactionsEnabled?: boolean;
9
  emitMetadata?: boolean;
10
  inputPosition?: 'top' | 'bottom';
11
  lang?: string;
12
}
13

14
const {
15
  repo,
16
  repoId,
17
  category,
18
  categoryId,
19
  mapping = 'pathname',
20
  reactionsEnabled = true,
21
  emitMetadata = false,
22
  inputPosition = 'bottom',
23
  lang = 'zh-CN'
24
} = Astro.props;
25
---
26

27
<div id="giscus-container"></div>
28

29
<script define:vars={{ repo, repoId, category, categoryId, mapping, reactionsEnabled, emitMetadata, inputPosition, lang }}>
30
  function loadGiscus() {
31
    const container = document.getElementById('giscus-container');
32
    if (!container) return;
33

34
    const isDark = document.documentElement.classList.contains('dark');
35
    const theme = isDark ? 'dark' : 'light';
36

37
    const script = document.createElement('script');
38
    script.src = 'https://giscus.app/client.js';
39
    script.setAttribute('data-repo', repo);
40
    script.setAttribute('data-repo-id', repoId);
41
    script.setAttribute('data-category', category);
42
    script.setAttribute('data-category-id', categoryId);
43
    script.setAttribute('data-mapping', mapping);
44
    script.setAttribute('data-strict', '0');
45
    script.setAttribute('data-reactions-enabled', reactionsEnabled ? '1' : '0');
46
    script.setAttribute('data-emit-metadata', emitMetadata ? '1' : '0');
47
    script.setAttribute('data-input-position', inputPosition);
48
    script.setAttribute('data-theme', theme);
49
    script.setAttribute('data-lang', lang);
50
    script.setAttribute('data-loading', 'lazy');
51
    script.crossOrigin = 'anonymous';
52
    script.async = true;
53

54
    container.appendChild(script);
55
  }
56

57
  // 监听主题变化
58
  function updateGiscusTheme() {
59
    const giscusFrame = document.querySelector('iframe[src*="giscus"]');
60
    if (giscusFrame) {
61
      const isDark = document.documentElement.classList.contains('dark');
62
      const theme = isDark ? 'dark' : 'light';
63

64
      giscusFrame.contentWindow.postMessage({
65
        giscus: {
66
          setConfig: {
67
            theme: theme
68
          }
69
        }
70
      }, 'https://giscus.app');
71
    }
72
  }
73

74
  // 监听DOM变化来检测主题切换
75
  const observer = new MutationObserver((mutations) => {
76
    mutations.forEach((mutation) => {
77
      if (mutation.type === 'attributes' && mutation.attributeName === 'class') {
78
        updateGiscusTheme();
79
      }
80
    });
81
  });
82

83
  // 页面加载时初始化
84
  if (document.readyState === 'loading') {
85
    document.addEventListener('DOMContentLoaded', loadGiscus);
86
  } else {
87
    loadGiscus();
88
  }
89

90
  // 开始观察主题变化
91
  observer.observe(document.documentElement, {
92
    attributes: true,
93
    attributeFilter: ['class']
94
  });
95
</script>

展开收起

添加到文章页面

在 src/pages/posts/[...slug].astro 文件中：
- 首先导入 Giscus 组件：

src/pages/posts/[...slug].astro展开收起

1
import path from "node:path";
2
import Giscus from "@components/misc/Giscus.astro";
3
import License from "@components/misc/License.astro";
4
import Markdown from "@components/misc/Markdown.astro";
5
import I18nKey from "@i18n/i18nKey";
6
import { i18n } from "@i18n/translation";
7
import MainGridLayout from "@layouts/MainGridLayout.astro";
8
import { getSortedPosts } from "@utils/content-utils";
9
import { getDir, getPostUrlBySlug } from "@utils/url-utils";
10
import { Icon } from "astro-icon/components";
11
import { licenseConfig } from "src/config";
12
import ImageWrapper from "../../components/misc/ImageWrapper.astro";
13
import PostMetadata from "../../components/PostMeta.astro";
14
import { profileConfig, siteConfig } from "../../config";
15
import { formatDateToYYYYMMDD } from "../../utils/date-utils";

展开收起

然后在许可证组件之后添加 Giscus 组件：

src/pages/posts/[...slug].astro展开收起

1
 <!-- always show cover as long as it has one -->
2

3
            {entry.data.image &&
4
                <ImageWrapper id="post-cover" src={entry.data.image} basePath={path.join("content/posts/", getDir(entry.id))} class="mb-8 rounded-xl banner-container onload-animation"/>
5
            }
6

7

8
            <Markdown class="mb-6 markdown-content onload-animation">
9
                <Content />
10
            </Markdown>
11

12
            {licenseConfig.enable && <License title={entry.data.title} slug={entry.slug} pubDate={entry.data.published} class="mb-6 rounded-xl license-container onload-animation"></License>}
13
            <!-- 评论模块 -->
14
            <Giscus
15
                repo="luozhipeng1/fuwari"
16
                repoId="R_kgDOPvEVqw"
17
                category="Announcements"
18
                categoryId="DIC_kwDOPvEVq84CwMEH"
19
            />
20
            <br>
21
        </div>
22
    </div>

展开收起

保存文件后重新构建项目即可看到评论区

通过以上步骤，你就成功为 Fuwari 添加了功能完善的评论系统，！🎉

给你的Fuwari添加一个友链页面

Fri, 03 Oct 2025 00:00:00 GMT

创建友链页面#

防404

在src\content\spec目录下新建文件friends.md，这个就是友链页面的文件

在src\types\config.ts文件内添加以下内容

src\types\config.ts

1
export enum LinkPreset {
2
  Home = 0,
3
  Archive = 1,
4
  About = 2,
5
  Friends = 3,
6
  Series = 4,
7
}

在src\i18n\i18nKey.ts文件内添加以下内容

src\i18n\i18nKey.ts展开收起


31 collapsed lines
1
enum I18nKey {
2
  home = "home",
3
  about = "about",
4
  archive = "archive",
5
  search = "search",
6

7
  tags = "tags",
8
  categories = "categories",
9
  recentPosts = "recentPosts",
10

11
  comments = "comments",
12

13
  untitled = "untitled",
14
  uncategorized = "uncategorized",
15
  noTags = "noTags",
16

17
  wordCount = "wordCount",
18
  wordsCount = "wordsCount",
19
  minuteCount = "minuteCount",
20
  minutesCount = "minutesCount",
21
  postCount = "postCount",
22
  postsCount = "postsCount",
23

24
  themeColor = "themeColor",
25

26
  lightMode = "lightMode",
27
  darkMode = "darkMode",
28
  systemMode = "systemMode",
29

30
  more = "more",
31

32
  author = "author",
33
  publishedAt = "publishedAt",
34
  license = "license",
35

36
  pinned = "pinned",
37

38
  series = "series",
39

40
  friends = "friends",
41
}
42

43
export default I18nKey;

展开收起

按照自己的语言，在 src\i18n\languages 目录中编辑相应语言文件这里拿 zh_CN.ts 举例：

src\i18n\languages\zh_CN.ts展开收起


34 collapsed lines
1
import Key from "../i18nKey";
2
import type { Translation } from "../translation";
3

4
export const zh_CN: Translation = {
5
  [Key.home]: "主页",
6
  [Key.about]: "关于",
7
  [Key.archive]: "归档",
8
  [Key.search]: "搜索",
9

10
  [Key.tags]: "标签",
11
  [Key.categories]: "分类",
12
  [Key.recentPosts]: "最新文章",
13

14
  [Key.comments]: "评论",
15

16
  [Key.untitled]: "无标题",
17
  [Key.uncategorized]: "未分类",
18
  [Key.noTags]: "无标签",
19

20
  [Key.wordCount]: "字",
21
  [Key.wordsCount]: "字",
22
  [Key.minuteCount]: "分钟",
23
  [Key.minutesCount]: "分钟",
24
  [Key.postCount]: "篇文章",
25
  [Key.postsCount]: "篇文章",
26

27
  [Key.themeColor]: "主题色",
28

29
  [Key.lightMode]: "亮色",
30
  [Key.darkMode]: "暗色",
31
  [Key.systemMode]: "跟随系统",
32

33
  [Key.more]: "更多",
34

35
  [Key.author]: "作者",
36
  [Key.publishedAt]: "发布于",
37
  [Key.license]: "许可协议",
38

39
  [Key.pinned]: "置顶",
40

41
  [Key.series]: "系列",
42

43
  [Key.friends]: "友链",
44
};

展开收起

举例展开收起

1
// en.ts
2
[Key.friends]: "Friends",
3

4
// es.ts
5
[Key.friends]: "Amigos",
6

7
// id.ts
8
[Key.friends]: "Teman",
9

10
// ja.ts
11
[Key.friends]: "友達",
12

13
// ko.ts
14
[Key.friends]: "친구",
15

16
// th.ts
17
[Key.friends]: "เพื่อน",
18

19
// tr.ts
20
[Key.friends]: "Arkadaşlar",
21

22
// vi.ts
23
[Key.friends]: "Bạn bè",
24

25
// zh_TW.ts
26
[Key.friends]: "友鏈",

展开收起

在 src\constants\link-presets.ts 文件内添加下方内容

src\constants\link-presets.ts展开收起

1
export const LinkPresets: { [key in LinkPreset]: NavBarLink } = {
2
  // ...
3
  [LinkPreset.Archive]: {
4
     name: i18n(I18nKey.archive),
5
     url: '/archive/',
6
   },
7
  [LinkPreset.Friends]: {
8
    name: i18n(I18nKey.friends),
9
    url: "/friends/",
10
   },
11
  [LinkPreset.Series]: {
12
    name: i18n(I18nKey.series),
13
    url: '/series/',
14
  },
15
}

展开收起

最后一步，在 src\config.ts 文件内添加内容，注意要在 LinkPreset.About 末尾添加,

src\config.ts

1
export const navBarConfig: NavBarConfig = {
2
  links: [
3
    LinkPreset.Home,
4
    LinkPreset.Archive,
5
    LinkPreset.About,
6
    LinkPreset.Friends,
7
    {
8
        // ....

在 src\pages 目录下，创建 friends.astro 文件

src\pages\friends.astro展开收起

1
---
2
import { getEntry, render } from "astro:content";
3
import Markdown from "@components/misc/Markdown.astro";
4
import I18nKey from "../i18n/i18nKey";
5
import { i18n } from "../i18n/translation";
6
import MainGridLayout from "../layouts/MainGridLayout.astro";
7

8
const friendsPost = await getEntry("spec", "friends");
9

10
if (!friendsPost) {
11
  throw new Error("friends page content not found");
12
}
13

14
const { Content } = await friendsPost.render();
15

16
const items = [
17
  {
18
    title: "鹏星导航",
19
    imgurl: "https://px.lzphy.top/favicon.ico",
20
    desc: "爱你所爱，一切美好！",
21
    siteurl: "https://px.lzphy.top",
22
    tags: ["html,前端"],
23
  },
24
];
25
---
26
<MainGridLayout title={i18n(I18nKey.friends)} description={i18n(I18nKey.friends)}>
27
    <div class="flex w-full rounded-[var(--radius-large)] overflow-hidden relative min-h-32">
28
        <div class="card-base z-10 px-9 py-6 relative w-full ">
29
            <div class="grid grid-cols-1 sm:grid-cols-2 gap-x-6 gap-y-8 my-4" id="friends-list">
30
                {items.map((item) => (
31
                  <div class="friend-card flex flex-nowrap items-stretch h-28 gap-4 rounded-[var(--radius-large)] hover:border-2 hover:border-blue-500 transition-all duration-300 ease-in-out cursor-pointer" data-url={item.siteurl}>
32
                    <div class="w-28 h-28 flex-shrink-0 rounded-lg overflow-hidden bg-zinc-200 dark:bg-zinc-900">
33
                      <img src={item.imgurl} alt="站点头像" class="w-full h-full object-cover" />
34
                    </div>
35
                    <div class="grow w-full">
36
                      <div class="font-bold transition text-lg text-neutral-900 dark:text-neutral-100 mb-1">{item.title}</div>
37
                      <div class="text-50 text-sm font-medium">{item.desc}</div>
38
                    </div>
39
                  </div>
40
                ))}
41
              </div>
42
            <Markdown class="mt-2">
43
                <Content />
44
            </Markdown>
45
        </div>
46
    </div>
47
 <!--在此处👇插入随机排列JS脚本 -->
48
 <script>
49
    window.addEventListener('DOMContentLoaded', () => {
50
        const container = document.getElementById('friends-list');
51
        if (!container) return;
52
        const cards = Array.from(container.children);
53
        // 洗牌算法
54
        for (let i = cards.length - 1; i > 0; i--) {
55
            const j = Math.floor(Math.random() * (i + 1));
56
            [cards[i], cards[j]] = [cards[j], cards[i]];
57
        }
58
        // 重新插入
59
        cards.forEach(card => container.appendChild(card));
60

61
        // 添加点击事件委托
62
        container.addEventListener('click', (e) => {
63
            if (e.target && e.target instanceof Element) {
64
                const friendCard = e.target.closest('.friend-card');
65
                if (friendCard) {
66
                    const url = (friendCard as HTMLElement).dataset.url;
67
                    if (url) {
68
                        window.open(url, '_blank');
69
                    }
70
                }
71
            }
72
        });
73
    });
74
    </script>
75
    <!--在此处👆插入随机排列JS脚本 -->
76

77
    <style>
78
       /* 定义一些变量 */
79
:root {
80
  --radius-large: 12px;
81
}
82

83
.friend-card:hover {
84
  border: 2px solid #007bff; /* 鼠标悬停时显示蓝色边框 */
85
  box-shadow: 0 4px 8px rgba(0, 0, 0, 0.1); /* 添加阴影效果 */
86
}
87
.friend-card:hover .font-bold {
88
  color: #007bff; /* 鼠标悬停时标题文字显示为蓝色 */
89
}
90
    </style>
91
</MainGridLayout>

展开收起

至此，友链页面完成创建

const items 部分就是添加的友链部分可以往下面继续添加

friends.md文章就是写页面介绍，和 about.md作用一样

Fuwari文章基础格式与Md扩展语法笔记

Fri, 26 Sep 2025 00:00:00 GMT

文章开头#

每篇通过pnpm new-post <文章名称>创建的文章，都会有的东西

开头标记

1
---
2
title: Fuwari文章基础格式与Md扩展语法笔记
3
published: 2025-09-26
4
updated: 2025-09-26
5
description: ''
6
image: ''
7
tags: [Fuwari,Markdown]
8
category: '笔记'
9
draft: false
10
lang: ''
11
pinned: false
12
series: ''
13
---

Attribute	Description
`title`	文章标题
`published`	文章发布日期
`updated`	文章更新日期，需要手动更改
`description`	文章描述
`image`	文章封面可以是绝对路径、相对路径或http链接
`tags`	文章标签
`category`	文章分类
`draft`	是否为草稿
`lang`	仅当文章语言与 `config.ts` 中的网站语言不同时需要设置
`pinned`	仅当置顶该文章时设置需修改新增配置才可使用默认不支持
`series`	文章同一系列

创建GitHub仓库卡片#

1
::github{repo="luozhipeng1/fuwari"}

例子：

luozhipeng1

fuwari

警告语法#

支持的警告类型如下: note tip important warning caution

语法警告展开收起

1
:::note
2
高亮内容，突出信息
3
:::
4

5
:::tip
6
提示性
7
:::
8

9
:::important
10
重点突出
11
:::
12

13
:::warning
14
警示性内容
15
:::
16

17
:::caution
18
警告性内容
19
:::
20

21
:::note[自定义标题]
22
自己取名
23
:::

展开收起

Note

高亮内容，突出信息

Tip

提示性

Important

重点突出

Warning

警示性内容

Caution

警告性内容

自定义标题

自己取名

GitHub提示语法#

1
> [!NOTE]
2
> The GitHub syntax is also supported.
3

4
> [!TIP]
5
> The GitHub syntax is also supported.

Note

The GitHub syntax is also supported.

Tip

The GitHub syntax is also supported.

IDEA 2025.2.2 最新破解版安装教程（附激活码，至2099年）

Fri, 26 Sep 2025 00:00:00 GMT

申明：本教程 IntelliJ IDEA 破解补丁、激活码均收集于网络，请勿商用，仅供个人学习使用，如有侵权，请联系作者删除。若条件允许，希望,大家购买正版！
本文提供三种激活方式，MAC，Windows，Linux均可使用
PS: 本教程最新更新时间: 2025年9月26日, 网站持续更新，收藏本站防失联哟~

废话不多说，先上 IDEA 2025.2.2 版本破解成功的截图，如下，可以看到已经成功破解到 2099 年辣，舒服！

image-20250926232520817

卸载老版本 IDEA#

接下来，我就将通过图文的方式, 来详细讲解如何激活 IDEA 2025.2.2 版本至 2099 年。首先，如果小伙伴的电脑上有安装老版本的 IDEA , 需要将其彻底卸载掉，如下所示（没有安装则不用管，直接安装即可）：

如果你之前使用过本站提供的激活到 2026 年版本脚本，需要执行对应卸载脚本，将自动添加的环境变量删除（若没使用过，则可忽略，继续下面的步骤）；

image-20250926194743218

将 删除缓存和本地历史 勾选上，点击卸载按钮开始卸载：

image-20250926194847414

卸载完成后，点击关闭按钮。

下载 IDEA 安装包#

访问 IDEA官网：https://www.jetbrains.com/idea/download/ ，下载 IDEA 2025.2.2 版本的安装包。

image-20250926195152218

开始安装#

下载完成后，双击 .exe 安装包开始安装 IDEA :

image-20250926195837134

点击 下一步 按钮：

image-20250926200804842

自定义安装路径，我这里安装在了 D:\ 盘下，继续点击 下一步 按钮：

image-20250926200858276

进入到 安装选项 的选择，将下图标注的部分，全部勾选上，点击 下一步 按钮：

image-20250926200936636

点击安装按钮，等待 IDEA 安装完成：

image-20250926201109891

安装成功后，会弹出如下提示框，运行 IntelliJ IDEA(R)

image-20250926201654800

点击完成按钮，关闭弹框。

下载破解脚本#

破解脚本我放置在了网盘中，并提供了多个备用链接，以防下载失效。

提示：破解脚本的网盘链接文末获取~
提示：破解脚本的网盘链接文末获取~
提示：破解脚本的网盘链接文末获取~

win11电脑首次安装

我本次安装是把电脑系统升级到win11，其次已经彻底卸载IDEA，可以当作电脑首次安装

启动 IDE#

双击桌面的 IDEA 快捷启动图标，来打开 IDEA 。注意，2024.2 之后的版本，若初次安装，会提示选择所在区域，如下图所示，如果选择了 China Mainland，会在激活的时候反复跳出激活码并提示激活码无效，原因是新版本会拦截 .cn 域名，导致激活许可被吊销，所以，千万不要指定区域！！

image-20250926203931715

如果是老用户，则可以在设置菜单中来更改（一定要更改）：

image-20250926204506996

开始激活(方式一网上多为使用版本)#

补丁下载成功后，记得先解压, 解压后的目录如下, 本文后面所需补丁都在下面标注的这个文件夹中：

image-20250926211847329

注意： 补丁所属文件夹需单独存放，且放置的路径不要有中文与空格，以免 IDEA 读取补丁错误。以后这个文件夹不要动

点击进入 /jetbra2026 补丁目录，再点击进入 /scripts 文件夹，双击执行 install-current-user.vbs 破解脚本：

image-20250926211954976

注意：如果执行脚本被安全软件提示有风险拦截，允许执行即可。

image-20250926212047040

会提示安装补丁需要等待数秒。点击【确定】按钮后，过程大概 5- 30 秒，如看到弹框提示 Done 时，表示激活破解成功：

image-20250926212914101

Mac / Linux 系统#

Mac / Linux 系统与上面 Windows 系统一样，需将补丁所属文件 /jetbra2026 复制到某个路径，且路径不能包含空格与中文。

之后，打开终端，进入到 /jetbra2026/scripts 文件夹，执行 install.sh 脚本, 命令如下：

1
sudo bash install.sh

看到提示 Done , 表示激活成功。

image-20250926212955456

部分小伙伴 Mac/Linux 系统执行脚本遇到如下错误：

image-20250926213011456

解决方法：

可先执行如下命令，再执行脚本：

1
export LC_COLLATE='C'
2
export LC_CTYPE='C'

image-20250926213035412

填入指定激活码完成激活#

重新打开 IDEA后，复制下面的激活码：

idea.key

1
FV8EM46DQYC5AW9-eyJsaWNlbnNlSWQiOiJGVjhFTTQ2RFFZQzVBVzkiLCJsaWNlbnNlZU5hbWUiOiJtZW5vcmFoIHBhcmFwZXQiLCJsaWNlbnNlZVR5cGUiOiJQRVJTT05BTCIsImFzc2lnbmVlTmFtZSI6IiIsImFzc2lnbmVlRW1haWwiOiIiLCJsaWNlbnNlUmVzdHJpY3Rpb24iOiIiLCJjaGVja0NvbmN1cnJlbnRVc2UiOmZhbHNlLCJwcm9kdWN0cyI6W3siY29kZSI6IlBDV01QIiwiZmFsbGJhY2tEYXRlIjoiMjAyNi0wOS0xNCIsInBhaWRVcFRvIjoiMjAyNi0wOS0xNCIsImV4dGVuZGVkIjp0cnVlfSx7ImNvZGUiOiJQUlIiLCJmYWxsYmFja0RhdGUiOiIyMDI2LTA5LTE0IiwicGFpZFVwVG8iOiIyMDI2LTA5LTE0IiwiZXh0ZW5kZWQiOnRydWV9LHsiY29kZSI6IlBEQiIsImZhbGxiYWNrRGF0ZSI6IjIwMjYtMDktMTQiLCJwYWlkVXBUbyI6IjIwMjYtMDktMTQiLCJleHRlbmRlZCI6dHJ1ZX0seyJjb2RlIjoiUFNJIiwiZmFsbGJhY2tEYXRlIjoiMjAyNi0wOS0xNCIsInBhaWRVcFRvIjoiMjAyNi0wOS0xNCIsImV4dGVuZGVkIjp0cnVlfSx7ImNvZGUiOiJJSSIsImZhbGxiYWNrRGF0ZSI6IjIwMjYtMDktMTQiLCJwYWlkVXBUbyI6IjIwMjYtMDktMTQiLCJleHRlbmRlZCI6ZmFsc2V9XSwibWV0YWRhdGEiOiIwMjIwMjQwNzAyUFNBWDAwMDAwNVgiLCJoYXNoIjoiMTIzNDU2NzgvMC01NDE4MTY2MjkiLCJncmFjZVBlcmlvZERheXMiOjcsImF1dG9Qcm9sb25nYXRlZCI6ZmFsc2UsImlzQXV0b1Byb2xvbmdhdGVkIjpmYWxzZSwidHJpYWwiOmZhbHNlLCJhaUFsbG93ZWQiOnRydWV9-cH8qBniG31nF8954hthJJuzF6Fk4RQ9T03IfNxsFkuxUcwaAGHKOcRudvBZIAbLwDDFw63q2QZsnpwthBb/6IqBYnJrjRC83a8wkYKGN8HqAyDtbqdLOxLjcaiAiSKzektfAXn6nGNfDeygcFr/WzMfI0on/43ByuwxmSrjwYc4M8SCR0nkDAi0XwXNnFp3vSp0gJQd+lJtkSHO2KR7gUyNDZOPVduljJGbdLJUK6UcUjrlAd6NrTNqpu5P7hcYRaNzjoJ0KeIx5k9KmMCdcfQBia/zSHUbwZiecFsyjxqtIU0C3TDaX1OM4siJVDpgrXi+ocY86hiiYE79ygJf2IA==-MIIETDCCAjSgAwIBAgIBDTANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1KZXRQcm9maWxlIENBMB4XDTIwMTAxOTA5MDU1M1oXDTIyMTAyMTA5MDU1M1owHzEdMBsGA1UEAwwUcHJvZDJ5LWZyb20tMjAyMDEwMTkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCUlaUFc1wf+CfY9wzFWEL2euKQ5nswqb57V8QZG7d7RoR6rwYUIXseTOAFq210oMEe++LCjzKDuqwDfsyhgDNTgZBPAaC4vUU2oy+XR+Fq8nBixWIsH668HeOnRK6RRhsr0rJzRB95aZ3EAPzBuQ2qPaNGm17pAX0Rd6MPRgjp75IWwI9eA6aMEdPQEVN7uyOtM5zSsjoj79Lbu1fjShOnQZuJcsV8tqnayeFkNzv2LTOlofU/Tbx502Ro073gGjoeRzNvrynAP03pL486P3KCAyiNPhDs2z8/COMrxRlZW5mfzo0xsK0dQGNH3UoG/9RVwHG4eS8LFpMTR9oetHZBAgMBAAGjgZkwgZYwCQYDVR0TBAIwADAdBgNVHQ4EFgQUJNoRIpb1hUHAk0foMSNM9MCEAv8wSAYDVR0jBEEwP4AUo562SGdCEjZBvW3gubSgUouX8bOhHKQaMBgxFjAUBgNVBAMMDUpldFByb2ZpbGUgQ0GCCQDSbLGDsoN54TATBgNVHSUEDDAKBggrBgEFBQcDATALBgNVHQ8EBAMCBaAwDQYJKoZIhvcNAQELBQADggIBABKaDfYJk51mtYwUFK8xqhiZaYPd30TlmCmSAaGJ0eBpvkVeqA2jGYhAQRqFiAlFC63JKvWvRZO1iRuWCEfUMkdqQ9VQPXziE/BlsOIgrL6RlJfuFcEZ8TK3syIfIGQZNCxYhLLUuet2HE6LJYPQ5c0jH4kDooRpcVZ4rBxNwddpctUO2te9UU5/FjhioZQsPvd92qOTsV+8Cyl2fvNhNKD1Uu9ff5AkVIQn4JU23ozdB/R5oUlebwaTE6WZNBs+TA/qPj+5/we9NH71WRB0hqUoLI2AKKyiPw++FtN4Su1vsdDlrAzDj9ILjpjJKA1ImuVcG329/WTYIKysZ1CWK3zATg9BeCUPAV1pQy8ToXOq+RSYen6winZ2OO93eyHv2Iw5kbn1dqfBw1BuTE29V2FJKicJSu8iEOpfoafwJISXmz1wnnWL3V/0NxTulfWsXugOoLfv0ZIBP1xH9kmf22jjQ2JiHhQZP7ZDsreRrOeIQ/c4yR8IQvMLfC0WKQqrHu5ZzXTH4NO3CwGWSlTY74kE91zXB5mwWAx1jig+UXYc2w4RkVhy0//lOmVya/PEepuuTTI4+UJwC7qbVlh5zfhj8oTNUXgN0AOc+Q0/WFPl1aw5VV/VrO8FCoB15lFVlpKaQ1Yh+DVU8ke+rt9Th0BCHXe0uZOEmH0nOnH/0onD

image-20250926213348262

成功激活，显示2026年，这里不用在意激活的时间，已经破解成功，可正常开发使用。

image-20250926213534832

开始激活(方式二推荐)，已经试用30天的，此方法有概率失败#

下载成功后，如下，是个EXE格式压缩包，先对它进行解压：

image-20250926202812640

进入到解压后的文件夹 /win2020-2024(一键激活) 中，双击IDEA激活.vbs，如果弹出Please launch your IntelliJIdea first!，这个就需要首先运行一下idea软件，打开就关闭，就是在电脑上跑一下idea软件而已。

image-20250926203109850

进入到解压后的文件夹 /win2020-2024(一键激活) 中，双击 IDEA激活.vbs ，若提示 Success!!! Now you can enjoy IntelliJIdea to 2099 , 则表示 IDEA 激活成功啦~

image-20250926204356843

检查是否激活成功#

激活成功后，双击桌面的 IDEA 快捷启动图标，来打开 IDEA 。进入 IDEA 中后，点击菜单 Help | Register , 即可查看 IDEA 的激活到期时间：如下图标注所示，根据日期显示直到 2099 年才会失效，确实是破解成功了：

image-20250926210743217

开始激活(方式三推荐)，正常情况100%成功#

下载这个文件夹

image-20250926213820942

找到 IDEA 软件的安装路径，小编的安装路径：D:\IntelliJ IDEA 2025.2.2\bin，同时使用记事本打开 idea64.exe.vmoptions

image-20250926214544552

在 idea64.exe.vmoptions 输入以下代码：

1
--add-opens=java.base/jdk.internal.org.objectweb.asm=ALL-UNNAMED
2
--add-opens=java.base/jdk.internal.org.objectweb.asm.tree=ALL-UNNAMED
3

4
#破解工具路径  需要换成自己的工具路径
5
-javaagent:D:\2020.3.4IDEAcrack\idea2099\active-idea.jar

image-20250926214741073

填入指定激活码完成激活#

重新打开 IDEA后，复制下面的激活码：

idea.key

1
9PPM13JQQY-eyJsaWNlbnNlSWQiOiI5UFBNMTNKUVFZIiwibGljZW5zZWVOYW1lIjoiY2F0IG1ldGhvZCIsImFzc2lnbmVlTmFtZSI6IiIsImFzc2lnbmVlRW1haWwiOiIiLCJsaWNlbnNlUmVzdHJpY3Rpb24iOiIiLCJjaGVja0NvbmN1cnJlbnRVc2UiOmZhbHNlLCJwcm9kdWN0cyI6W3siY29kZSI6IlBXUyIsImZhbGxiYWNrRGF0ZSI6IjIwMjMtMDYtMDEiLCJwYWlkVXBUbyI6IjIwMjMtMDYtMDEiLCJleHRlbmRlZCI6dHJ1ZX0seyJjb2RlIjoiUERCIiwiZmFsbGJhY2tEYXRlIjoiMjAyMy0wNi0wMSIsInBhaWRVcFRvIjoiMjAyMy0wNi0wMSIsImV4dGVuZGVkIjp0cnVlfSx7ImNvZGUiOiJQU1ciLCJmYWxsYmFja0RhdGUiOiIyMDIzLTA2LTAxIiwicGFpZFVwVG8iOiIyMDIzLTA2LTAxIiwiZXh0ZW5kZWQiOnRydWV9LHsiY29kZSI6IlBSQiIsImZhbGxiYWNrRGF0ZSI6IjIwMjMtMDYtMDEiLCJwYWlkVXBUbyI6IjIwMjMtMDYtMDEiLCJleHRlbmRlZCI6dHJ1ZX0seyJjb2RlIjoiUFNJIiwiZmFsbGJhY2tEYXRlIjoiMjAyMy0wNi0wMSIsInBhaWRVcFRvIjoiMjAyMy0wNi0wMSIsImV4dGVuZGVkIjp0cnVlfSx7ImNvZGUiOiJQR08iLCJmYWxsYmFja0RhdGUiOiIyMDIzLTA2LTAxIiwicGFpZFVwVG8iOiIyMDIzLTA2LTAxIiwiZXh0ZW5kZWQiOnRydWV9LHsiY29kZSI6IlBQUyIsImZhbGxiYWNrRGF0ZSI6IjIwMjMtMDYtMDEiLCJwYWlkVXBUbyI6IjIwMjMtMDYtMDEiLCJleHRlbmRlZCI6dHJ1ZX0seyJjb2RlIjoiUFBDIiwiZmFsbGJhY2tEYXRlIjoiMjAyMy0wNi0wMSIsInBhaWRVcFRvIjoiMjAyMy0wNi0wMSIsImV4dGVuZGVkIjp0cnVlfSx7ImNvZGUiOiJQQ1dNUCIsImZhbGxiYWNrRGF0ZSI6IjIwMjMtMDYtMDEiLCJwYWlkVXBUbyI6IjIwMjMtMDYtMDEiLCJleHRlbmRlZCI6dHJ1ZX0seyJjb2RlIjoiSUkiLCJmYWxsYmFja0RhdGUiOiIyMDIzLTA2LTAxIiwicGFpZFVwVG8iOiIyMDIzLTA2LTAxIiwiZXh0ZW5kZWQiOmZhbHNlfV0sIm1ldGFkYXRhIjoiMDEyMDIyMDYwMVBTQU4wMDAwMDUiLCJoYXNoIjoiVFJJQUw6LTE5NzMwODYzMiIsImdyYWNlUGVyaW9kRGF5cyI6NywiYXV0b1Byb2xvbmdhdGVkIjpmYWxzZSwiaXNBdXRvUHJvbG9uZ2F0ZWQiOmZhbHNlfQ==-P0n5WNbm7POecGXoOAsmSv9RVkBrrKm5PvBN59x/mXNvetWjgbQf6p926HduPz58bg+3SdpPDPWkcWtY06El7L/XXZVvWwKwlvdR6Vkhy1+GRiuu56Ix1JBO9cM1evwDYW21wpr0KMJ3zaLA6Vi9BUm/N8a39G4PaZn+rVdSjVwRFjF7bt5rIqOktkLe7UM6os5Z4RxcX7h7/rpVlpPwlg1teMu/+BLaP7AzFZNLY58HUJhub00TaYoOVuiYu+WozZIIBHdrmPWnS372qV2Vu+NZPksjlTqcxXM8LOhuZcuFZtlVsXMrgIoxUni+FRjwf57BYADXfhxX+iOl3kh2uQ==-MIIETDCCAjSgAwIBAgIBDTANBgkqhkiG9w0BAQsFADAYMRYwFAYDVQQDDA1KZXRQcm9maWxlIENBMB4XDTIwMTAxOTA5MDU1M1oXDTIyMTAyMTA5MDU1M1owHzEdMBsGA1UEAwwUcHJvZDJ5LWZyb20tMjAyMDEwMTkwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQCUlaUFc1wf+CfY9wzFWEL2euKQ5nswqb57V8QZG7d7RoR6rwYUIXseTOAFq210oMEe++LCjzKDuqwDfsyhgDNTgZBPAaC4vUU2oy+XR+Fq8nBixWIsH668HeOnRK6RRhsr0rJzRB95aZ3EAPzBuQ2qPaNGm17pAX0Rd6MPRgjp75IWwI9eA6aMEdPQEVN7uyOtM5zSsjoj79Lbu1fjShOnQZuJcsV8tqnayeFkNzv2LTOlofU/Tbx502Ro073gGjoeRzNvrynAP03pL486P3KCAyiNPhDs2z8/COMrxRlZW5mfzo0xsK0dQGNH3UoG/9RVwHG4eS8LFpMTR9oetHZBAgMBAAGjgZkwgZYwCQYDVR0TBAIwADAdBgNVHQ4EFgQUJNoRIpb1hUHAk0foMSNM9MCEAv8wSAYDVR0jBEEwP4AUo562SGdCEjZBvW3gubSgUouX8bOhHKQaMBgxFjAUBgNVBAMMDUpldFByb2ZpbGUgQ0GCCQDSbLGDsoN54TATBgNVHSUEDDAKBggrBgEFBQcDATALBgNVHQ8EBAMCBaAwDQYJKoZIhvcNAQELBQADggIBAB2J1ysRudbkqmkUFK8xqhiZaYPd30TlmCmSAaGJ0eBpvkVeqA2jGYhAQRqFiAlFC63JKvWvRZO1iRuWCEfUMkdqQ9VQPXziE/BlsOIgrL6RlJfuFcEZ8TK3syIfIGQZNCxYhLLUuet2HE6LJYPQ5c0jH4kDooRpcVZ4rBxNwddpctUO2te9UU5/FjhioZQsPvd92qOTsV+8Cyl2fvNhNKD1Uu9ff5AkVIQn4JU23ozdB/R5oUlebwaTE6WZNBs+TA/qPj+5/we9NH71WRB0hqUoLI2AKKyiPw++FtN4Su1vsdDlrAzDj9ILjpjJKA1ImuVcG329/WTYIKysZ1CWK3zATg9BeCUPAV1pQy8ToXOq+RSYen6winZ2OO93eyHv2Iw5kbn1dqfBw1BuTE29V2FJKicJSu8iEOpfoafwJISXmz1wnnWL3V/0NxTulfWsXugOoLfv0ZIBP1xH9kmf22jjQ2JiHhQZP7ZDsreRrOeIQ/c4yR8IQvMLfC0WKQqrHu5ZzXTH4NO3CwGWSlTY74kE91zXB5mwWAx1jig+UXYc2w4RkVhy0//lOmVya/PEepuuTTI4+UJwC7qbVlh5zfhj8oTNUXgN0AOc+Q0/WFPl1aw5VV/VrO8FCoB15lFVlpKaQ1Yh+DVU8ke+rt9Th0BCHXe0uZOEmH0nOnH/0onD

image-20250926215012147

历史版本下载链接：#

https://www.jetbrains.com/idea/download/other.html ，找到想要的版本，下载对应系统的安装包即可。

激活脚本下载地址#

夸克网盘：https://pan.quark.cn/s/ad4df2db1124

百度网盘：https://pan.baidu.com/s/1U7edqb2B-fGm1yz4D7D7QA?pwd=pyxh

UC网盘：https://drive.uc.cn/s/e69d33d2ebef4?public=1

第三种方案文件获取（手机上复制口令到对应的浏览器或者网盘打开）

下载地址：UC口令-----> 嗖开发工具全家桶扣聆

下载地址：夸克口令-----> 动作壬曲鳢噤蠡多好

下载地址：训雷口令-----> 鹏摇星海

Windows10 它居然不更新了

Thu, 25 Sep 2025 00:00:00 GMT

真的无语了

最近几天天天弹窗，这个win10他不更新了，搞得我现在升级win11，使用起来好别扭！

相比较win10，首先这个win11桌面图标有放大的意思，其次鼠标右键用起来是真的难受，还有弹窗在win11中不能完全置底，无论怎么搞，都会露出几十px个像素，不能当前看不见了。

最尼玛离谱的win11这个运行内存，好像有啥大病似的，

我刚安装完win11，电脑重启后发现运行内存直接占用70%，卧槽，这他娘的直接快给我干傻了，吓得我赶紧打开任务管理器去看内存条插槽，我发现一切都好，但是告诉我使用了10GB内存，我是真的无语，我完全不晓得这个内存用在哪个地方，后面我打开多个浏览器网页+软件，我发现这个内存占用还是70%浮动，我就感觉这个win11是不是内置了一个虚拟机，他这个内存是动态浮动，它先给你谎报一个大内存，但是实际上并没有使用，是一个虚的，需要我们一点一点的使用才能填满，我是真的无语！

虽然网上有解决win11虚拟内存的办法，但我比较懒，只要不影响我，就随它吧！不过该吐槽还是得吐槽。

现在更迭好快啊，我记得小时候还是win7，当然啦，我小时候没见过，我第一次摸到电脑就已经是win10了，那个时候网吧里面还在流行打CF，那些大佬是真的猛啊！不过随着时间流逝我也是换上了win11，当初win11刚出时，我更新过一次，不过当场又换回来了，现在没办法了，win10以后也会和win7一样被人遗忘，以后的小孩接触的就是win11或者更高的版本了

Fuwari 部署指南（教程）

Mon, 22 Sep 2025 00:00:00 GMT

一、前言#

折腾过不少博客框架，比如 VanBlog、Halo、Word Press，它们都提供了简洁易用的后台功能和优雅的文章管理体验。虽然动态博客框架功能强大，但需要定期维护服务器和数据库，长期使用下来成本较高。

随着现代前端技术的飞速发展，我逐渐转向静态站点的方案。最终，我选择了基于 Astro 框架和 fuwari 主题的静态博客，简单易上手，部署便捷，非常适合专注写作和内容分享。

🌟 Astro 是啥？#

简单说，Astro 是一个做静态网站的框架，特别适合像博客、个人主页、文档站这种内容为主的网站。它的一个大优点就是：不用管前端那些花里胡哨的东西也能做出超快的网页。

我自己选它，主要是因为它：

默认几乎不带 JavaScript，打开速度嗖嗖的；
写文章直接用 Markdown，配图、加代码块都很方便；
想加点互动？它也支持 React、Vue、Svelte 这些框架，而且可以混着用；
页面是“静态”的，部署超简单，丢到 GitHub Pages、Vercel、Netlify 都行；
最重要的，对我这种懒人来说：写完就丢线上，不用操心服务器和数据库。

✨ fuwari功能特性#

基于 Astro 和 Tailwind CSS 开发
流畅的动画和页面过渡
亮色 / 暗色模式
自定义主题色和横幅图片
响应式设计
评论
搜索
文内目录

二、搭建需求#

开始之前，先准备些东西！#

Git：版本控制工具，拿来上传、同步代码用的，基本操作得会一点。
Node.js：因为 Fuwari 主题是跑在 Node.js 上的，所以必须先装它。
GitHub 账号：博客文件要有个“家”，就放在 GitHub 的仓库里。
Cloudflare 账号：部署博客用的，可以帮你免费生成一个可以访问的网址。如果你更喜欢用 Vercel、Netlify 或 GitHub Pages 也完全没问题～
一个顺手的 Markdown 编辑器：比如 Typora 或 MarkText，写文章超级方便。如果 Markdown 语法不太熟，戳这学习下 👉 Markdown 教程

开搞吧#

三、本地部署Fuwari#

仓库#

withastro

astro

https://us.umami.is/websites/f11536ad-eac1-434b-a0c7-fc78faa63405

使用此模板生成新仓库或 Fork 此仓库
进行本地开发，Clone 新的仓库，执行pnpm install
- 若未安装 pnpm，执行 npm install -g pnpm
至此部署成功执行 pnpm dev ,即可本地运行

四、博客配置#

1.基本配置#

你可以通过配置文件 src/config.ts 自定义博客，这里以我自己的配置文件为例：

博客基本内容：#

注意

下面用其他颜色标记的是我改动的地方，其他的都是默认，不过在部署的过程中，随便改改玩，试试每一个的效果

src/config.ts 的 siteConfig展开收起

1
export const siteConfig: SiteConfig = {
2
  title: "PengXing's Blog", // 标题
3
  subtitle: "爱你所爱！", // 副标题
4
  lang: "zh_CN", // 'en', 'zh_CN', 'zh_TW', 'ja', 'ko', 'es', 'th' 语言设置
5
  themeColor: {
6
    hue: 250, // 主题色的色调范围从0到360。例如：红色：0，青色：200，蓝色：250，粉色：345
7
    fixed: false, // 是否隐藏主题颜色选择器，访客可见
8
  },
9
  banner: {
10
    enable: true, // 是否启用横幅
11
    src: "assets/images/demo-banner.png", // 横幅图片的路径，相对于 /src 目录，如果路径以 / 开头则相对于 /public 目录，或者完整路径的网络图片
12
    position: "center", // 横幅位置，对应 object-position 属性，只支持 'top', 'center', 'bottom'，默认为 'center'
13
    credit: {
14
      enable: false, // 是否显示横幅图片的版权信息
15
      text: "", // 显示的版权文字
16
      url: "", // （可选）指向原始艺术作品或艺术家页面的 URL 链接
17
    },
18
  },
19
  toc: {
20
    enable: true, // 是否在文章右侧显示目录
21
    depth: 2, // 显示目录的最大标题深度，从 1 到 3
22
  },
23
  favicon: [
24
    // 留空数组以使用默认的 favicon
25
    {
26
      src: "/favicon/favicon.ico", // favicon 的路径，相对于 /public 目录
27
      theme: "light", // （可选）设置为 'light' 或 'dark'，仅当有不同的 favicon 时才设置
28
      sizes: "32x32", // （可选）favicon 的尺寸，仅当有不同尺寸的 favicon 时设置
29
    },
30
  ],
31
};

展开收起

个人信息与联系方式：#

src/config.ts 的 profileConfig展开收起

1
export const profileConfig: ProfileConfig = {
2
  avatar: "assets/images/demo-avatar.png", // 头像路径，相对于 /src 目录，如果路径以 / 开头则相对于 /public 目录
3
  name: "鹏星",
4
  bio: "Love what you love,  all will be well! / 爱你所爱，一切美好！", // 个人简介
5
  links: [
17 collapsed lines
6
    // {
7
    //   name: "Twitter",
8
    //   icon: "fa6-brands:twitter", // Visit https://icones.js.org/ for icon codes
9
    //   // You will need to install the corresponding icon set if it's not already included
10
    //   // `pnpm add @iconify-json/<icon-set-name>`
11
    //   url: "https://twitter.com",
12
    // },
13
    // {
14
    //   name: "Steam",
15
    //   icon: "fa6-brands:steam",
16
    //   url: "https://store.steampowered.com",
17
    // },
18
    // {
19
    //   name: "GitHub",
20
    //   icon: "fa6-brands:github",
21
    //   url: "https://github.com/saicaca/fuwari",
22
    // },
23
    {
24
      name: "QQ频道",
25
      icon: "fa6-brands:qq",
26
      url: "https://pd.qq.com/s/38it5vmzn",
27
    },
28
    {
29
      name: "link3",
30
      icon: "fa6-brands:staylinked",
31
      url: "https://link3.cc/pyxh",
32
    },
33
  ],
34
};

展开收起

2. 创建文章#

在src/content/posts/目录中创建.md或终端中执行 pnpm new-post <filename> 创建新文章并编辑。

文章格式：#

注意

最新的 fuwari ，新建文章可能没有updated，需要自行到scripts\new-post.js配置

scripts\new-post.js

1
const content = `---
2
title: ${args[0]}
3
published: ${getDate()}
4
updated: ${getDate()}
5
description: ''
6
image: ''
7
tags: []
8
category: ''
9
draft: false
10
lang: ''
11
pinned: false
12
series: ''
13
---
14
`;

demo.md

1
---
2
title: 新文章  # 文章标题
3
published: 2025-09-22        # 发布时间
4
updated: 2025-09-22          # 最后更新时间,后面文章更新需要手动更改
5
description: '创建新的文章'      # 简短描述，用于概述文章内容
6
image: ./img.jpg  //文章封面，可留空
7
tags: [ 文章, 个人]  # 标签列表，方便分类和搜索
8
category: '日常'              # 所属分类
9
draft: false                  # 是否为草稿（true 表示尚未发布）
10
lang: 'ja'      //仅当文章语言与 `config.ts` 中的网站语言不同时需要设置
11
---

五、部署上线#

1.准备工作#

部署前需编辑 astro.config.mjs ,改为你的域名

astro.config.mjs

1
// https://astro.build/config
2
export default defineConfig({
3
  site: "https://pengxing.dpdns.org/", // 站点地址
4
  base: "/",
5
  trailingSlash: "always",
6
  integrations: [
7
    tailwind({
8
      nesting: true,
9
    }),
10
        // ..........
11
}

2.连接至Cloudflare#

官方指南将博客部署至 Cloudflare,Vercel, Netlify, GitHub Pages 等；

本篇只介绍Cloudflare(本人在用)

连接至Cloudflare#

前往Cloudflare的创建一个Pages#

image-20250922202011512

选择导入现有Git存储库,连接你的Github#

image-20250922202124173

设置构建命令：`pnpm build` ，然后设置构建输出目录：`dist`#

image-20250922202316351

到这里就结束了，你只需要在本地编写文章，然后用Git将更改推送到远程仓库，Cloudflare就会自动部署，用Cloudflare分配给你的链接即可访问博客

有域名的话绑定自定域名#

image-20250922202418303

四、个性化#

1.添加ICP备案和运行时间#

在 src/components/Footer.astro 文件中例:

src\components\Footer.astro展开收起

1
---
2

3
import { profileConfig } from "../config";
4
import { url } from "../utils/url-utils";
5
const currentYear = new Date().getFullYear();
6
---
7

8
<!--<div class="border-t border-[var(&#45;&#45;primary)] mx-16 border-dashed py-8 max-w-[var(&#45;&#45;page-width)] flex flex-col items-center justify-center px-6">-->
9
<div class="transition border-t border-black/10 dark:border-white/15 my-10 border-dashed mx-32"></div>
10
<!--<div class="transition bg-[oklch(92%_0.01_var(&#45;&#45;hue))] dark:bg-black rounded-2xl py-8 mt-4 mb-8 flex flex-col items-center justify-center px-6">-->
11
<div class="transition border-dashed border-[oklch(85%_0.01_var(--hue))] dark:border-white/15 rounded-2xl mb-12 flex flex-col items-center justify-center px-6">
12
    <div class="transition text-50 text-sm text-center">
13
        &copy; <span id="copyright-year">{currentYear}</span> {profileConfig.name}. All Rights Reserved. /
14
        Powered by
15
        <a class="transition link text-[var(--primary)] font-medium" target="_blank" href="https://astro.build">Astro</a> &
16
        <a class="transition link text-[var(--primary)] font-medium" target="_blank" href="https://github.com/saicaca/fuwari">Fuwari</a>
17
        <br>
18
        <a class="transition link text-[var(--primary)] font-medium" + target="_blank" href="https://beian.miit.gov.cn/">
19
            ICP备XXXXXXXXX号-1</a>
20
    </div>
21
    <script type="text/javascript">function runtime(){const t=new Date("07/01/2023 08:00:00"),n=new Date,s=n-t,e=Math.floor(s/1e3),o=Math.floor(e/86400),i=Math.floor(e%86400/3600),a=Math.floor(e%3600/60),r=e%60;document.getElementById("runningtime").innerHTML=`✨本站竟然运行了: ${o}天${i}小时${a}分${r}秒 ☁🤩`}setInterval(runtime,1e3)</script>
22
    <div class="transition text-50 text-sm text-center hidden md:block"><p id="runningtime"> </p></div>
23
</div>

展开收起

Fuwari链接卡片

Mon, 22 Sep 2025 00:00:00 GMT

第一种实现方案链接卡片#

参考了feat: add link-card feature

小声说
我采用这个方法，使用起来怪怪的，就放弃了，链接虽然直接就转为卡片，但是自主性太差了

第一种实现方案#

创建组件新建一个src/plugins/rehype-component-link-card.mjs组件

src/plugins/rehype-component-link-card.mjs展开收起

1
/// <reference types="mdast" />
2
import { h } from "hastscript";
3

4
// 常量定义
5
const CONSTANTS = {
6
  FAVICON_API: 'https://www.google.com/s2/favicons',
7
  FAVICON_SIZE: 32,
8
  ID_PREFIX: 'LC',
9
  LOADING_TITLE: 'Loading...',
10
  LOADING_DESC: 'Loading description...',
11
};
12

13
// 错误信息
14
const ERRORS = {
15
  INVALID_DIRECTIVE: 'Invalid directive. ("link-card" directive must be leaf type "::link-card{url="https://example.com"}")',
16
  INVALID_URL: 'Invalid URL. ("url" attribute must be a valid HTTP/HTTPS URL)',
17
};
18

19
/**
20
 * 生成唯一的卡片ID
21
 * 使用时间戳和随机数确保唯一性
22
 */
23
function generateCardId() {
24
  const timestamp = Date.now().toString(36);
25
  const random = Math.random().toString(36).slice(2, 8);
26
  return `${CONSTANTS.ID_PREFIX}${timestamp}${random}`;
27
}
28

29
/**
30
 * 安全地提取域名
31
 */
32
function extractDomain(url) {
33
  try {
34
    return new URL(url).hostname;
35
  } catch {
36
    return 'unknown';
37
  }
38
}
39

40
/**
41
 * 验证URL是否有效
42
 */
43
function isValidUrl(url) {
44
  if (!url) return false;
45
  try {
46
    const urlObj = new URL(url);
47
    return ['http:', 'https:'].includes(urlObj.protocol);
48
  } catch {
49
    return false;
50
  }
51
}
52

53
/**
54
 * 转义字符串用于安全插入到JavaScript中
55
 */
56
function escapeForScript(str) {
57
  return JSON.stringify(str);
58
}
59

60
/**
61
 * 生成获取元数据的脚本
62
 * 使用IIFE避免全局污染，使用JSON.stringify防止XSS
63
 */
64
function generateMetadataScript(cardId, url, domain) {
65
  return `
66
    (function() {
67
      'use strict';
68
      try {
69
        const cardElement = document.getElementById('${cardId}-card');
70
        const titleElement = document.getElementById('${cardId}-title');
71
        const descElement = document.getElementById('${cardId}-description');
72

73
        if (!cardElement || !titleElement || !descElement) {
74
          console.warn('[LINK-CARD] Elements not found for ${cardId}');
75
          return;
76
        }
77

78
        // 只有在没有自定义内容时才设置默认值
79
        if (!titleElement.dataset.hasCustomTitle) {
80
          titleElement.textContent = ${escapeForScript(domain)};
81
        }
82
        if (!descElement.dataset.hasCustomDesc) {
83
          descElement.textContent = ${escapeForScript(`Visit ${domain}`)};
84
        }
85

86
        cardElement.classList.remove("fetch-waiting");
87
        console.log("[LINK-CARD] Loaded card for:", ${escapeForScript(url)}, "|", "${cardId}");
88
      } catch (err) {
89
        console.error("[LINK-CARD] Error loading card:", err);
90
        const cardEl = document.getElementById('${cardId}-card');
91
        if (cardEl) {
92
          cardEl.classList.add("fetch-error");
93
          cardEl.classList.remove("fetch-waiting");
94
        }
95
      }
96
    })();
97
  `;
98
}
99

100
/**
101
 * Creates a Link Card component for third-party links.
102
 * @param {Object} properties - The properties for the link card
103
 * @param {string} properties.url - The URL to link to (required)
104
 * @param {string} [properties.title] - Custom title for the card
105
 * @param {string} [properties.description] - Custom description
106
 * @param {string} [properties.image] - Custom image URL
107
 * @param {string} [properties.icon] - Custom favicon URL
108
 * @param {Array} children - Should be empty for leaf directive
109
 * @returns {Object} HAST element representing the link card
110
 */
111
export function LinkCardComponent(properties = {}, children = []) {
112
  // 验证：确保是叶子指令（没有子元素）
113
  if (Array.isArray(children) && children.length !== 0) {
114
    return h("div", { class: "hidden" }, ERRORS.INVALID_DIRECTIVE);
115
  }
116

117
  // 验证URL
118
  if (!isValidUrl(properties.url)) {
119
    return h("div", { class: "hidden" }, ERRORS.INVALID_URL);
120
  }
121

122
  const url = properties.url;
123
  const domain = extractDomain(url);
124
  const cardId = generateCardId();
125

126
  // 解构自定义属性，提供默认值
127
  const {
128
    title: customTitle = null,
129
    description: customDescription = null,
130
    image: customImage = null,
131
    icon: customIcon = null
132
  } = properties;
133

134
  // 判断是否需要获取元数据
135
  const needsFetch = !customTitle || !customDescription;
136

137
  // 构建favicon URL，使用自定义图标或Google的favicon服务
138
  const iconUrl = customIcon ||
139
    `${CONSTANTS.FAVICON_API}?domain=${encodeURIComponent(domain)}&sz=${CONSTANTS.FAVICON_SIZE}`;
140

141
  // 创建favicon元素
142
  const nFavicon = h(`div#${cardId}-favicon`, {
143
    class: "lc-favicon",
144
    style: `background-image: url(${iconUrl})`,
145
    // 添加错误处理：如果图标加载失败，使用默认背景色
146
    onerror: "this.style.backgroundImage='none'; this.style.backgroundColor='#f0f0f0';"
147
  });
148

149
  // 创建标题栏
150
  const nTitle = h("div", { class: "lc-titlebar" }, [
151
    h("div", { class: "lc-titlebar-left" }, [
152
      h("div", { class: "lc-site" }, [
153
        nFavicon,
154
        h("div", { class: "lc-domain" }, domain),
155
      ]),
156
    ]),
157
    h("div", { class: "lc-external-icon" }),
158
  ]);
159

160
  // 创建卡片标题
161
  const nCardTitle = h(
162
    `div#${cardId}-title`,
163
    {
164
      class: "lc-card-title",
165
      ...(customTitle && { 'data-has-custom-title': 'true' })
166
    },
167
    customTitle || CONSTANTS.LOADING_TITLE
168
  );
169

170
  // 创建描述
171
  const nDescription = h(
172
    `div#${cardId}-description`,
173
    {
174
      class: "lc-description",
175
      ...(customDescription && { 'data-has-custom-desc': 'true' })
176
    },
177
    customDescription || CONSTANTS.LOADING_DESC
178
  );
179

180
  // 构建卡片内容数组
181
  const cardContent = [nTitle, nCardTitle, nDescription];
182

183
  // 如果有自定义图片，添加图片元素
184
  if (customImage) {
185
    const nImage = h(
186
      `div#${cardId}-image`,
187
      { class: "lc-image" },
188
      h("img", {
189
        src: customImage,
190
        alt: customTitle || "Link preview",
191
        loading: "lazy", // 添加懒加载
192
        onerror: "this.style.display='none';" // 图片加载失败时隐藏
193
      })
194
    );
195
    cardContent.push(nImage);
196
  }
197

198
  // 如果需要获取元数据，添加脚本
199
  if (needsFetch) {
200
    const nScript = h(
201
      `script#${cardId}-script`,
202
      {
203
        type: "text/javascript",
204
        defer: true
205
      },
206
      generateMetadataScript(cardId, url, domain)
207
    );
208
    cardContent.push(nScript);
209
  }
210

211
  // 创建并返回链接卡片
212
  return h(
213
    `a#${cardId}-card`,
214
    {
215
      class: needsFetch ? "card-link fetch-waiting no-styling" : "card-link no-styling",
216
      href: url,
217
      target: "_blank",
218
      rel: "noopener noreferrer", // 安全性：防止新页面访问 window.opener
219
      'data-url': url,
220
      'aria-label': `Link to ${domain}`, // 无障碍：添加屏幕阅读器标签
221
      title: customTitle || `Visit ${domain}` // 添加悬停提示
222
    },
223
    cardContent
224
  );
225
}
226

227
// 导出默认函数，保持向后兼容
228
export default LinkCardComponent;

展开收起

新建样式我这里选择新建src/styles/link-card.styl,当然也可以选择在src/styles/markdown-extend.styl中添加以下样式

样式
这里参考鱼的样式

src/styles/link-card.styl展开收起

1
// Link Card Styles
2
a.card-link
3
  display: block
4
  text-decoration: none
5
  border: 1px solid var(--line-divider)
6
  border-radius: 8px
7
  padding: 16px
8
  margin: 16px 0
9
  background-color: var(--card-bg)
10
  transition: all 0.2s ease
11
  position: relative
12
  overflow: hidden
13
  color: inherit
14

15
  &:hover
16
    background-color: var(--btn-regular-bg-hover)
17

18
    .lc-titlebar
19
      .lc-external-icon
20
        opacity: 1
21

22
  &:active
23
    transform: translateY(0)
24
    box-shadow: 0 2px 10px rgba(0, 0, 0, 0.1)
25

26
  .lc-titlebar
27
    display: flex
28
    justify-content: space-between
29
    align-items: center
30
    margin-bottom: 8px
31

32
    .lc-titlebar-left
33
      display: flex
34
      align-items: center
35

36
    .lc-site
37
      display: flex
38
      align-items: center
39
      gap: 8px
40

41
    .lc-favicon
42
      width: 16px
43
      height: 16px
44
      background-size: contain
45
      background-repeat: no-repeat
46
      background-position: center
47
      flex-shrink: 0
48

49
    .lc-domain
50
      font-size: 14px
51
      color: var(--text-color-secondary)
52
      font-weight: 500
53

54
    .lc-external-icon
55
      width: 16px
56
      height: 16px
57
      opacity: 0.6
58
      transition: opacity 0.2s ease
59
      background-image: url('data:image/svg+xml;utf8,<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6"></path><polyline points="15,3 21,3 21,9"></polyline><line x1="10" y1="14" x2="21" y2="3"></line></svg>')
60
      background-size: contain
61
      background-repeat: no-repeat
62
      background-position: center
63

64
  .lc-card-title
65
    font-size: 18px
66
    font-weight: 600
67
    color: var(--text-color-primary)
68
    margin-bottom: 8px
69
    line-height: 1.3
70

71
  .lc-description
72
    font-size: 14px
73
    color: var(--text-color-secondary)
74
    line-height: 1.4
75
    margin-bottom: 12px
76

77
  .lc-image
78
    margin-top: 12px
79

80
    img
81
      width: 100%
82
      max-height: 200px
83
      object-fit: cover
84
      border-radius: 4px
85

86
  &.fetch-waiting
87
    .lc-card-title, .lc-description
88
      animation: pulse 1.5s ease-in-out infinite
89

90
  &.fetch-error
91
    border-color: var(--error-color)
92
    background-color: var(--error-bg)
93

94
@keyframes pulse
95
  0%, 100%
96
    opacity: 1
97
  50%
98
    opacity: 0.5

展开收起

然后在src/styles/markdown-extend.styl中导入

src/styles/markdown-extend.styl

1
@import 'link-card.styl' // 在文件末尾添加就行

配置Astro 在astro.config.mjs文件中导入组件并注册

astro.config.mjs

1
// 添加导入
2
import { LinkCardComponent } from "./src/plugins/rehype-component-link-card.mjs";
3

4
// 在 rehypeComponents 配置中添加
5
rehypeComponents,
6
{
7
  components: {
8
    "link-card": LinkCardComponent, // 添加这一行
9
    // ... 其他组件
10
  },
11
},

使用方法#

注意

确保URL以http://或https://开头

自定义图片建议使用合适的尺寸和格式 '''

demo.md

1
// 基本用法
2
::link-card{url="https://example.com"}
3

4
// 自定义标题和描述
5
::link-card{url="https://github.com" title="GitHub" description="代码托管平台"}
6

7
// 带自定义图片
8
::link-card{url="https://vercel.com" title="Vercel" description="部署平台" image="https://example.com/image.png"}
9

10
// 自定义图标
11
::link-card{url="https://github.com" title="GitHub" description="代码托管平台" icon="https://github.com/favicon.ico"}
12

13
// 我自定义的
14
::link-card{url="https://pengxing.dpdns.org/posts/umami-uv--pv-%E7%BB%9F%E8%AE%A1%E6%98%BE%E7%A4%BA/" title="Umami UV / PV 统计显示" description="Umami 统计显示" icon="https://pengxing.dpdns.org/favicon/favicon.ico" image="https://pengxing.dpdns.org/_astro/image-20250916112203340.CqtaXT93_Z1Bppgg.webp" }

Fuwari链接外部跳转

Mon, 22 Sep 2025 00:00:00 GMT

话说在前#

用 Fuwari 模板搭建博客的各位肯定遇到过这种情况:

网站内的链接点击直接在内部跳转,而不是新标签页打开（就很烦! ）

那么,在灌水的时候也是看到群U分享了一个很好用的插件可以解决这个问题

使用方法#

使用包管理器安装rehype-external-links插件

以pnpm举例

rehype-external-links

1
pnpm add rehype-external-links

修改astro.config.mjs,导入并配置

astro.config.mjs展开收起

1
其他导入...
2

3
// 导入rehype-external-links插件
4
import rehypeExternalLinks from 'rehype-external-links';
5

6
...
7

8
  markdown: {
9
    rehypePlugins: [
10
      [
11
        rehypeExternalLinks,
12
        {
13
        target: '_blank',
14
        },
15
      ],
16
...

展开收起

然后我们就大功告成了

在Fuwari中添加系列页面

Mon, 22 Sep 2025 00:00:00 GMT

前言
接上回 《在Fuwari中添加系列栏》
在导航栏上加一个系列按钮，点击进入，可以看到一个用来查看所有系列的页面

改动点#

修改src\constants\link-presets.ts、src\config.ts、src\types\config.ts三个文件

src\constants\link-presets.ts

1
export const LinkPresets: { [key in LinkPreset]: NavBarLink } = {
2
  // ...
3
  [LinkPreset.Friends]: {
4
    name: i18n(I18nKey.friends),
5
    url: '/friends/',
6
  },
7
  [LinkPreset.Series]: {
8
    name: i18n(I18nKey.series),
9
    url: '/series/',
10
  },
11
}

src\config.ts

1
export const navBarConfig: NavBarConfig = {
2
  links: [
3
    LinkPreset.Home,
4
    LinkPreset.Archive,
5
    LinkPreset.Series,
6
    LinkPreset.About,
7
    LinkPreset.Friends,
5 collapsed lines
8
    {
9
      name: 'GitHub',
10
      url: 'https://github.com/ikamusume7/fuwari',     // Internal links should not include the base path, as it is automatically added
11
      external: true,                               // Show an external link icon and will open in a new tab
12
    },
13
  ],
14
}

src\types\config.ts

1
export enum LinkPreset {
2
  Home = 0,
3
  Archive = 1,
4
  About = 2,
5
  Friends = 3,
6
  Series = 4,
7
}

新增src\pages\series.astro、src\components\SeriesPanel.astro两个文件

src\pages\series.astro

1
---
2
import MainGridLayout from '@layouts/MainGridLayout.astro'
3
import SeriesPanel from '@components/SeriesPanel.astro'
4
import { i18n } from '@i18n/translation'
5
import I18nKey from '@i18n/i18nKey'
6
---
7

8
<MainGridLayout title={i18n(I18nKey.series)}>
9
    <SeriesPanel></SeriesPanel>
10
</MainGridLayout>

src\components\SeriesPanel.astro展开收起

1
---
2
import { UNCATEGORIZED } from '@constants/constants'
3
import I18nKey from '../i18n/i18nKey'
4
import { i18n } from '../i18n/translation'
5
import { getSortedPosts } from '../utils/content-utils'
6
import { getPostUrlBySlug } from '../utils/url-utils'
7
import { getCategoryUrl } from '../utils/url-utils'
8

9
interface Props {
10
  keyword?: string
11
  tags?: string[]
12
  categories?: string[]
13
}
14

15
let posts = await getSortedPosts()
16

17
interface Series {
18
  count: number
19
  name: string
20
  posts: typeof posts
21
}
22

23
const groups: { category: string; series: Series[] }[] = (() => {
24
  const groupedSeries = posts.reduce(
25
    (grouped: { [category: string]: {[seriesName: string]: Series} }, post) => {
26
      const category = post.data.category || UNCATEGORIZED
27
      const series = post.data.series || UNCATEGORIZED
28
      if (category == UNCATEGORIZED || series === UNCATEGORIZED) {
29
        return grouped
30
      }
31
      if (!grouped[category]) {
32
        grouped[category] = {}
33
      }
34
      if (!grouped[category][series]) {
35
        grouped[category][series] = {
36
          count: 0,
37
          name: series,
38
          posts: [],
39
        }
40
      }
41
      grouped[category][series].count++
42
      grouped[category][series].posts.push(post)
43
      return grouped
44
    },
45
    {},
46
  )
47

48
  // convert the object to an array
49
  const groupedSeriesArray = Object.keys(groupedSeries).map(key => ({
50
    category: key,
51
    series: Object.values(groupedSeries[key]),
52
  }))
53

54
  return groupedSeriesArray
55
})()
56
---
57

58
<div class="card-base px-8 py-6">
59
    {
60
        groups.map(group => (
61
            <div>
62
                <div class="flex flex-row w-full items-center h-[3.75rem]">
63
                    <div class="w-[20%] md:w-[15%] transition text-2xl font-bold text-right text-75 flex flex-row justify-end">
64
                      <a aria-label={group.category} href={getCategoryUrl(group.category)}
65
                          class="btn-plain scale-animation rounded-lg h-11 font-bold px-2 active:scale-95"
66
                      >
67
                          {group.category}
68
                      </a>
69
                    </div>
70
                    <div class="w-[15%] md:w-[10%]">
71
                        <div class="h-3 w-3 bg-none rounded-full outline outline-[var(--primary)] mx-auto -outline-offset-[2px] z-50 outline-3"></div>
72
                    </div>
73
                    <div class="w-[65%] md:w-[75%] transition text-left text-50">{group.series.length} 个{i18n(I18nKey.series)}</div>
74
                </div>
75
                {group.series.map(series => (
76
                    <a href={getPostUrlBySlug(series.posts[series.posts.length-1].slug)}
77
                       aria-label={series.name}
78
                       class="group btn-plain !block h-10 w-full rounded-lg hover:text-[initial]"
79
                    >
80
                        <div class="flex flex-row justify-start items-center h-full">
81
                            <!-- count -->
82
                            <div class="w-[20%] md:w-[15%] transition text-sm text-right text-50">
83
                                { series.count } 篇文章
84
                            </div>
85
                            <!-- dot and line -->
86
                            <div class="w-[15%] md:w-[10%] relative dash-line h-full flex items-center">
87
                                <div class="transition-all mx-auto w-1 h-1 rounded group-hover:h-5
88
                                bg-[oklch(0.5_0.05_var(--hue))] group-hover:bg-[var(--primary)]
89
                                outline outline-4 z-50
90
                                outline-[var(--card-bg)]
91
                                group-hover:outline-[var(--btn-plain-bg-hover)]
92
                                group-active:outline-[var(--btn-plain-bg-active)]
93
                                "
94
                                ></div>
95
                            </div>
96
                            <!-- post title -->
97
                            <div class="w-[65%] md:max-w-[75%] md:w-[75%] text-left font-bold
98
                                group-hover:translate-x-1 transition-all group-hover:text-[var(--primary)]
99
                                text-75 pr-8 whitespace-nowrap overflow-ellipsis overflow-hidden"
100
                            >
101
                                    {series.name}
102
                            </div>
103
                        </div>
104
                    </a>
105
                ))}
106
            </div>
107
        ))
108
    }
109
</div>

展开收起

在Fuwari中添加系列栏

Fri, 19 Sep 2025 00:00:00 GMT

系列相当于是对同一分类下的文章进行再细分
当查看某篇文章时，如果它属于某一个系列，在名片栏与分类栏中间会多出一个系列栏，里面会列出同系列的所有文章

示例#

在md文件上方配置项中添加series，只要系列名相同就会被归类为同一系列

demo.md

1
---
2
title: 在Fuwari中添加系列栏
3
published: 2025-09-19
4
updated: 2025-09-22
5
description: ''
6
image: ''
7
tags: []
8
category: ''
9
draft: false
10
lang: ''
11
pinned: false
12
series: ''
13
---

改动点#

修改📁i18n里的文件，增加seriesKey

src\i18n\i18nKey.ts

1
enum I18nKey {
2
    // ...
3
    series = 'series',
4
}
5

6
export default I18nKey

src\i18n\languages\en.ts

1
export const es: Translation = {
2
    // ...
3
    [Key.series]: 'Serie',
4
}

src\i18n\languages\es.ts

1
export const es: Translation = {
2
    // ...
3
    [Key.series]: 'Serie',
4
}

src\i18n\languages\ja.ts

1
export const ja: Translation = {
2
    // ...
3
    [Key.series]: 'シリーズ',
4
}

src\i18n\languages\th.ts

1
export const ko: Translation = {
2
    // ...
3
    [Key.series]: 'ชุด',
4

5
}

src\i18n\languages\zh_CN.ts

1
export const zh_CN: Translation = {
2
    // ...
3
    [Key.series]: '系列',
4

5
}

src\i18n\languages\zh_TW.ts

1
export const zh_TW: Translation = {
2
    // ...
3
    [Key.series]: '系列',
4

5
}

在两个config文件里增加series字段

src\types\config.ts

1
export type BlogPostData = {
2
  // ...
3
  series?: string
4
  prevTitle?: string
5
  prevSlug?: string
6
  nextTitle?: string
7
  nextSlug?: string
8
}

src\content\config.ts

1
const postsCollection = defineCollection({
2
  schema: z.object({
3
    // ...
4
    lang: z.string().optional().default(''),
5
    series: z.string().optional(),
6

7
    /* For internal use */
8
    prevTitle: z.string().default(''),
9
    // ...
10
  }),
11
})

修改[...slug]页面，将series传入MainGridLayout组件

src\pages\posts[...slug].astro

1
<MainGridLayout banner={entry.data.image} title={entry.data.title}
2
    description={entry.data.description} lang={entry.data.lang}
3
    setOGTypeArticle={true} series={entry.data.series}>
4

5
</MainGridLayout>

修改MainGridLayout组件里的三处代码，接收series并将其传入SideBar组件

src\layouts\MainGridLayout.astro展开收起

1
---
2
interface Props {
3
  title?: string
4
  banner?: string
5
  description?: string
6
  lang?: string
7
  setOGTypeArticle?: boolean;
8
  series?: string
9
}
10

11
const { title, banner, description, lang, setOGTypeArticle, series } = Astro.props
12
---
13

14
<SideBar class="mb-4 row-start-2 row-end-3 col-span-2 lg:row-start-1 lg:row-end-2 lg:col-span-1 lg:max-w-[17.5rem] onload-animation"
15
    series={ series }>
16
</SideBar>

展开收起

在content-utils.ts里添加getPostSeries方法

src\utils\content-utils.ts展开收起

1
export async function getPostSeries(
2
  seriesName: string,
3
): Promise<{ body: string; data: BlogPostData; slug: string }[]> {
4
  const posts = (await getCollection('posts', ({ data }) => {
5
    return (
6
      (import.meta.env.PROD ? data.draft !== true : true) &&
7
      data.series === seriesName
8
    )
9
  })) as unknown as { body: string; data: BlogPostData; slug: string }[]
10

11
  posts.sort((a, b) => {
12
    const dateA = new Date(a.data.published)
13
    const dateB = new Date(b.data.published)
14
    return dateA > dateB ? 1 : -1
15
  })
16

17
  return posts
18
}

展开收起

📁widget里新增Series组件

src\components\widget\Series.astro展开收起

1
---
2
import I18nKey from '../../i18n/i18nKey'
3
import { i18n } from '../../i18n/translation'
4
import { getPostSeries } from '../../utils/content-utils'
5
import { getPostUrlBySlug } from '../../utils/url-utils'
6
import WidgetLayout from './WidgetLayout.astro'
7

8
const COLLAPSED_HEIGHT = '7.5rem'
9

10
interface Props {
11
  class?: string
12
  style?: string
13
  series: string
14
}
15
const className = Astro.props.class
16
const style = Astro.props.style
17
const seriesName = Astro.props.series
18

19
const series = await getPostSeries(seriesName)
20

21
const isCollapsed = series.length >= 10
22
---
23
<WidgetLayout name={i18n(I18nKey.series) + " - " + series[0].data.series} id="series" isCollapsed={isCollapsed} collapsedHeight={COLLAPSED_HEIGHT} class={className} style={style}>
24
    <div class="flex flex-col gap-1">
25
        {series.map(t => (
26
            <a href={getPostUrlBySlug(t.slug)}
27
                aria-label={t.data.title}
28
                class="group btn-plain h-10 w-full rounded-lg hover:text-[initial]"
29
            >
30
                <!-- dot and line -->
31
                <div class="w-[15%] md:w-[10%] relative dash-line h-full flex items-center">
32
                    <div class="transition-all mx-auto w-1 h-1 rounded group-hover:h-5
33
                    bg-[oklch(0.5_0.05_var(--hue))] group-hover:bg-[var(--primary)]
34
                    outline outline-4 z-50
35
                    outline-[var(--card-bg)]
36
                    group-hover:outline-[var(--btn-plain-bg-hover)]
37
                    group-active:outline-[var(--btn-plain-bg-active)]
38
                    "
39
                    ></div>
40
                </div>
41
                <!-- post title -->
42
                <div class="w-[85%] text-left font-bold
43
                    group-hover:translate-x-1 transition-all group-hover:text-[var(--primary)]
44
                    text-75 pr-15 whitespace-nowrap overflow-ellipsis overflow-hidden" title={t.data.title}
45
                >
46
                        {t.data.title}
47
                </div>
48
            </a>
49
        ))}
50
    </div>
51
</WidgetLayout>

展开收起

在SideBar组件中导入Series组件，接收series并将其传入Series组件

src\components\widget\SideBar.astro展开收起

1
---
2
import Profile from './Profile.astro'
3
import Tag from './Tags.astro'
4
import Categories from './Categories.astro'
5
import type { MarkdownHeading } from 'astro'
6
import TOC from './TOC.astro'
7
import Series from './Series.astro'
8

9
interface Props {
10
    class? : string
11
    headings? : MarkdownHeading[]
12
    series?: string
13
}
14

15
const className = Astro.props.class
16
const headings = Astro.props.headings
17
const series = Astro.props.series
18

19
---
20
<div id="sidebar" class:list={[className, "w-full"]}>
21
    <div class="flex flex-col w-full gap-4 mb-4">
22
        <Profile></Profile>
23
    </div>
24
    <div id="sidebar-sticky" class="transition-all duration-700 flex flex-col w-full gap-4 top-4 sticky top-4">
25
        <div id="series" class="flex flex-col w-full gap-4">
26
            { series && <Series series={ series }></Series> }
27
        </div>
28
        <Categories class="onload-animation" style="animation-delay: 150ms"></Categories>
29
        <Tag class="onload-animation" style="animation-delay: 200ms"></Tag>
30
    </div>
31
</div>

展开收起

在 swup 的 containers 配置项里加上#series

astro.config.mjs展开收起

1
export default defineConfig({
2
  integrations: [
3
    swup({
4
      theme: false,
5
      animationClass: "transition-swup-", // see https://swup.js.org/options/#animationselector
6
      // the default value `transition-` cause transition delay
7
      // when the Tailwind class `transition-all` is used
8
      containers: ["main", "#toc", "#series"],
9
      smoothScrolling: true,
10
      cache: true,
11
      preload: true,
12
      accessibility: true,
13
      updateHead: true,
14
      updateBodyClass: false,
15
      globalInstance: true,
16
    }),
17
  ],
18
});

展开收起

增强Fuwari的代码块功能

Wed, 17 Sep 2025 00:00:00 GMT

使用现在最新的🍥Fuwari博客已经引入了astro-expressive-code包，不需要额外安装了，直接使用就完事了
折叠与行数都已经配置好了，@expressive-code/plugin-collapsible-sections 与 @expressive-code/plugin-line-numbers 不用额外安装

使用格式方法#

标题#

标题

1
console.log("Line 1");
2
console.log("Line 2");
3
let a = 1;
4
let b = 2;

高亮指定行#

1
console.log("Line 1");
2
console.log("Line 2");
3
let a = 1;
4
let b = 2;
5
let c = 3;
6
let d = 4;
7
let e = 5;
8
let f = 6;
9
let g = 7;
10
console.log(a + b);
11
let h = 4;
12
let i = 5;
13
let j = 6;
14
let k = 7;
15
let l = 7;

展开收起

新增/删除指定行#

1
console.log("Line 1");
2
console.log("Line 2");
3
let a = 1;
4
let b = 2;
5
let c = 3;
6
let d = 4;
7
let e = 5;
8
let f = 6;
9
let g = 7;
10
console.log(a + b);
11
let h = 4;
12
let i = 5;
13
let j = 6;
14
let k = 7;
15
let l = 7;

展开收起

高亮块#

1
```js  "a + b" del="let g = 7"
2
//{2,4-5}高亮 ins={3,7}新增 del={6}删除
3
console.log("Line 1");
4
console.log("Line 2");
5
let a = 1;
6
let b = 2;
7
let c = 3;
8
let d = 4;
9
let e = 5;
10
let f = 6;
11
let g = 7;
12
console.log(a + b);
13
let h = 4;
14
let i = 5;
15
let j = 6;
16
let k = 7;
17
let l = 7;

展开收起

折叠代码/代码行数#

7
//collapse={8-13, 15-16} 折叠 startLineNumber=7
8
console.log("Line 1");
9
console.log("Line 2");
10
let a = 1;
11
let b = 2;
12
let c = 3;
13
let d = 4;
6 collapsed lines
14
let e = 5;
15
let f = 6;
16
let g = 7;
17
console.log(a + b);
18
let h = 4;
19
let i = 5;
20
let j = 6;
2 collapsed lines
21
let k = 7;
22
let l = 7;

展开收起

代码块标识#

这是一个Expressive Code的插件，增加代码块的语言标识图标

安装依赖包

1
# 使用 npm
2
npm install @xt0rted/expressive-code-file-icons --save
3

4
# 如果用 pnpm（从报错中的 .pnpm 来看可能是你的包管理器）
5
pnpm add @xt0rted/expressive-code-file-icons

这是博主的设置，修改样式后需删除项目里的📁.astro，并重启项目才能看到效果

astro.config.mjs展开收起

1
import { pluginFileIcons } from "@xt0rted/expressive-code-file-icons";
2

3
export default defineConfig({
4
  // ...
5
  integrations: [
6
    // ...
7
    expressiveCode({
8
    themes: ["catppuccin-frappe", "light-plus"],
9
    plugins: [pluginCollapsibleSections(), pluginLineNumbers(),
10
      pluginFileIcons({
11
        iconClass: "text-4 w-5 inline mr-1 mb-1",
12
        titleClass: ""
13
      })
14
    ],
15
  }),
16
  ]
17
})

展开收起

提醒

不过有些标识图标不适用双主题，比如 Astro 下面是博主的临时解决办法（针对Astro）

src\components\LightDarkSwitch.svelte展开收起

1
onMount(() => {
2
  mode = getStoredTheme();
3
    updateAstroSvg(mode);
4
  const darkModePreference = window.matchMedia("(prefers-color-scheme: dark)");
5
  const changeThemeWhenSchemeChanged: Parameters<
6
    typeof darkModePreference.addEventListener<"change">
7
  >[1] = (_e) => {
8
    applyThemeToDocument(mode);
9
  };
10
  darkModePreference.addEventListener("change", changeThemeWhenSchemeChanged);
11
  return () => {
12
    darkModePreference.removeEventListener(
13
      "change",
14
      changeThemeWhenSchemeChanged,
15
    );
16
  };
17
});
18

19
function switchScheme(newMode: LIGHT_DARK_MODE) {
20
  mode = newMode;
21
  setTheme(newMode);
22
    updateAstroSvg(mode);
23
}
24
function updateAstroSvg(mode: LIGHT_DARK_MODE) {
25
  const spans = document.querySelectorAll('figcaption > .title')
26
  spans.forEach(span => {
27
    if (!span || !span.innerHTML.includes('astro')) return
28

29
    const paths = span.querySelectorAll('svg > path')
30
    if (mode === DARK_MODE){
31
      paths[1].setAttribute('fill', '#fff')
32
    }
33
    else{
34
      paths[1].setAttribute('fill', '#000')
35
    }
36
  })
37
}

展开收起

Umami UV / PV 统计显示

Tue, 16 Sep 2025 00:00:00 GMT

Umami 官方文档并没有提供 UV 和 PV 展示的 API，但是我们可以通过 Umami 的访客 API 获取到网站的访问量和访问人数。
本文将介绍如何通过 Umami 的 API 获取网站的 UV 和 PV 数据，并在页面上展示。

这是本站的 Umami 访问统计页面，显示了每日的访问量和访问人数，链接：

image-20250916104118792

我们在前文介绍过如何安装 Umami：Umami 安装使用教程

下面我们将新建用户，通过 Umami 的 API 调用，编写一个简单的页面来显示 Umami 的 UV, PV 访问情况。本文使用类似于 postman 的 API 测试工具来发送 GET, POST 请求。你也可以使用 hoppscotch、curl 等工具。

1. 新建 `View only` 权限的用户#

点击 Settings -> 点击 Users -> 点击 Create user -> 填写账号密码，Role 选择 View only -> 点击 Save

image-20250916104609380

肯定有读者很疑惑，为什么不直接调用 Umami 的 API 获取数据，而是要额外创建一个账户。
因为我的博客是 静态开源无服务器 的，所有代码都展示在前端，包括 API 调用。而 Umami 的 admin API 权限太大了，如果使用 admin 权限的 API Token，那么这个 token 可以获取、修改、删除所有网站的数据，会有严重的安全隐患。
所以我们需要创建一个 View only 权限的用户，使用这个 低权限的用户的 API Token 来访问我们的浏览量等数据。

2. 新建 `Team` 并添加用户和网站#

点击 Settings -> 点击 Teams -> 点击 Create team -> 填写名称 -> 点击 Save

Teams 中选择你刚创建的 Team 点击 view -> 复制 Access code，点击 Websites，点击 Add website 添加你想共享的网站。

image-20250916105721328

如果你的网站之前属于个人账户，那么你可以将其转移到团队账户上。

image-20250916110027185

换一个浏览器登录 Umami（使用 View only 权限的用户） -> Settings -> Teams -> Join team -> 输入 Access code -> Join -> 如果没有出错的话，点击 Dashboard 就可以看到你刚刚添加的网站了。

3. 获取 `View only` 用户的 API Token#

1
POST /api/auth/login

例如你的网站地址为 example.com，那么你需要使用 View only 的账户密码向 https://example.com/api/auth/login 发送一个 POST 请求，请求体为：

1
{
2
  "username": "your-username",
3
  "password": "your-password"
4
}

如果成功，你应该会得到以下的结果：

1
{
2
    "token": "39FFnY1og2MSPWg46alFZfS++akKpey37bRcp9D3oH6CsCMvaCbClN2Qbqq0QhUyZBD1FlHQ9UzUwYOS+J0JKSYnOR7SjftGEuCGj+QBY9RFHxJQBJtpZJmtBvodjgsY0ov8e3jLIClNsfyAecZ3RDXnarsZt+hZwRAFL+5WlOShQP1Bg6e6UyJuUD7f/NWfU94C0ZKYkAgg3b66ATWnkh23UuM3LP3EyYBiQXX3T2PmtN5gSFf7XkS0yRLOP4OCkKUn15j6KzGWHkFsWalwfIz3yECPdZgEWZyDtAnxB5i52N/+t9XIdiR2TDy1LpNj7h7D/dgfue6YO9U5akCauecGniXD7ZPdP1awPvXC/oOLl8TzQCuL+yM0JMN8",
3
    "user": {
4
        "id": "41e2b680-648e-4b09-bcd7-3e2b10c06264",
5
        "username": "admin",
6
        "role": "admin",
7
        "createdAt": "2025-09-15T02:10:42.209Z",
8
        "isAdmin": true
9
    }
10
}

保存 token 值，并在所有请求中发送带 Bearer <token> 值的 Authorization 标头。请求标头应该如下所示：

1
Authorization: Bearer 39FFnY1og2MSPWg46a...yM0JMN8

image-20250916110646498

4. 发送请求获取数据#

先分析一下官方文档的 API 接口：

1
# 获取网站所有数据汇总
2
GET /api/websites/{websiteId}/stats

API

有两个必填的查询参数：startAt 和 endAt，都是 Unix 毫秒时间戳，表示开始时间和结束时间

websiteId 和 startAt 需要我们自己获取

websiteId 可以在 Dashboard -> 点击你网站的 View details -> 浏览器栏的地址 https://example.com/websites/{websiteId} 中找到 {websiteId}

1
https://example.com/websites/8dd154a4-2073-415e-830e-3a82444b6bb6

如上链接中的 8dd154a4-2073-415e-830e-3a82444b6bb6 就是 websiteId。

startAt 可发送 GET 请求到 https://example.com/api/websites/{websiteId}，带上上文获取的请求头

1
Authorization: Bearer 39FFnY1og2MSPWg46a...yM0JMN8

在返回结果中找到 createdAt 字段，这个字段就是 startAt 的值，也就是你的网站创建时间，数据的开始时间

createdAt

5. 编写页面#

页面展示

1
<!DOCTYPE html>
2
<html lang="en">
3

4
<head>
5
    <meta charset="UTF-8">
6
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
7
    <title>Document</title>
8
</head>
9

10
<body>
11
    <div style="text-align:center;">
12
        <h1>Umami 网站统计</h1>
13
        <span>总访问量 <span id="umami-site-pv"></span> 次</span>
14

15
        <span>总访客数 <span id="umami-site-uv"></span> 人</span>
16
    </div>
17

18
    <script>
19
        // umami 的 website id
20
        const website_id = 'xxx';
21

22
        // 拼接请求地址
23
        const request_url = 'https://xxx.com' + '/api/websites/' + website_id + '/stats';
24

25
        const start_time = new Date('2024-01-01').getTime(); // 你的网站创建时间
26
        const end_time = new Date().getTime();
27

28
        const token = 'xxxxxx';
29

30
        // 检查配置是否为空
31
        if (!website_id) {
32
            throw new Error("Umami website_id is empty");
33
        }
34
        if (!request_url) {
35
            throw new Error("Umami request_url is empty");
36
        }
37
        if (!start_time) {
38
            throw new Error("Umami start_time is empty");
39
        }
40
        if (!token) {
41
            throw new Error("Umami token is empty");
42
        }
43

44
        const params = new URLSearchParams({
45
            startAt: start_time,
46
            endAt: end_time,
47
        });
48

49
        const request_header = {
50
            method: "GET",
51
            headers: {
52
                "Content-Type": "application/json",
53
                "Authorization": "Bearer " + token,
54
            },
55
        };
56

57
        async function allStats() {
58
            try {
59
                const response = await fetch(`${request_url}?${params}`, request_header);
60
                const data = await response.json();
61
                const uniqueVisitors = data.uniques.value; // 获取独立访客数
62
                const pageViews = data.pageviews.value; // 获取页面浏览量
63

64
                let ele1 = document.querySelector("#umami-site-pv")
65
                if (ele1) {
66
                    ele1.textContent = pageViews; // 设置页面浏览量
67
                }
68

69
                let ele2 = document.querySelector("#umami-site-uv")
70
                if (ele2) {
71
                    ele2.textContent = uniqueVisitors;
72
                }
73

74
                console.log(uniqueVisitors, pageViews);
75
                console.log(data);
76
            } catch (error) {
77
                console.error(error);
78
                return "-1";
79
            }
80
        }
81
        allStats();
82
    </script>
83
</body>
84

85
</html>

展开收起

Umami 安装使用教程

Tue, 16 Sep 2025 00:00:00 GMT

Umami is a simple, fast, privacy-focused alternative to Google Analytics.
Umami 是一个简单、快速、注重隐私的 Google Analytics 替代品。

image-20250916112203340

1. 什么是 Umami，为什么要使用它？#

Umami 是一个简单、快速、注重隐私的开源分析解决方案，是 Google Analytics 的替代品。可轻松收集、分析和了解您的网络数据，同时维护访客隐私和数据所有权。不收集个人身份信息，不使用 Cookie，所有数据都经过匿名处理，符合 GDPR。

它是一个网站统计工具，可以帮助你分析网站的访问情况，比如访问量、访问来源、访问时间等等。这对于静态网站来说是非常有用的，因为静态网站无法像动态网站一样通过后端代码来统计访问情况。

2. 安装 Umami#

1Panel 或宝塔一键安装

打开 1Panel 或宝塔 面板，点击 应用商店，搜索 umami，点击 安装 即可。

🛠从源码安装

要求

具有 Node.js 版本 18.18 或更高版本的服务器
数据库。Umami 支持 MariaDB （最低版本 v10.5）、 MySQL （最低版本 v8.0）和 PostgreSQL （最低版本 v12.14）数据库。
安装 Yarn

Terminal window

1
npm install -g yarn

获取源码并安装依赖

Terminal window

1
git clone https://github.com/umami-software/umami.git
2
cd umami
3
yarn install

配置 Umami 创建一个 .env 文件，内容如下：

Terminal window

1
DATABASE_URL=connection-url

其中 connection-url 为数据库连接地址，如

Terminal window

1
postgresql://username:mypassword@localhost:5432/mydb
2
mysql://username:mypassword@localhost:3306/mydb

构建 Umami

Terminal window

1
# 服务器不太行的，卡死这步概率极大
2
yarn build

启动 Umami

Terminal window

1
yarn start

docker-compose 安装

下载官方的 docker-compose.yml 文件：

Terminal window

1
wget https://raw.githubusercontent.com/umami-software/umami/master/docker-compose.yml

docker-compose.yml 的默认数据库是 Postgresql 数据库，如果你想使用 MySQL 数据库，可以修改 docker-compose.yml，将 DATABASE_URL 的 postgres 替换为 mysql，并修改 DATABASE_URL 为 MySQL 对应的链接。

修改完配置参数后运行：

Terminal window

1
docker-compose up -d

默认情况下，应用程序将在 http://localhost:3000 上启动。建议使用反向代理避免直接暴露端口。

3. 修改 Umami 密码#

Umami 启动后，默认用户名为 admin，默认密码为 umami。

我们先修改密码，选择 Setting -> Profile，然后设置你的新密码。

img

修改密码

点击右上角的地球图标，修改语言为 中文。

4. 添加网站#

点击 设置 -> 网站 -> 添加网站，输入你的网站地址，点击 添加 即可。

添加网站

填写信息后，点击 编辑

编辑

再点击 跟踪代码，复制代码到你的网站中即可。

跟踪代码

1
<script async src="https://example.com/script.js" data-website-id="xxxxxxxxxxxxxxxxxxxx"></script>

如果你在本地写博客，你会发现 localhost 也被统计了，可以添加 data-domains 属性，只统计你的域名：

1
<script async src="https://example.com/script.js" data-website-id="xxxxxxxxxxxxxxxxxxxx" data-domains="example.com"></script>

如果你想遵循访客的 Do Not Track 设置，可以添加 data-do-not-track 属性：

1
<script async src="https://example.com/script.js" data-website-id="xxxxxxxxxxxxxxxxxxxx" data-do-not-track="true"></script>

更多使用方法请参考官方文档：https://umami.is/docs/tracker-configuration

5. Umami UV / PV 统计显示#

Umami 官方文档并没有直接提供 UV 和 PV 展示的 API，但是我们可以通过编写相应的代码来获取 Umami 的访问量和访问人数。具体操作参考我的另一篇文章：

静态博客展示文章浏览量

Tue, 16 Sep 2025 00:00:00 GMT

引言#

如果你用过WordPress，Halo等动态博客框架，你大概会在用户视角访问博文的时候看到浏览量这个信息。

这个原理很简单，因为动态博客依赖于一个VPS，只需要让用户每次访问的时候给浏览量+1即可。

那么如果我们是静态博客呢？

我们可以依赖一些第三方服务，比如Umami Cloud。在你的静态博客的head注入一个js，这样你就可以看到你的站点分析了，类似下图

image-20250916234245274

现在我们可以看到网站整体的访问量和每个文章（即/posts/xxx）的访问量了，但是我们要如何展示给用户呢？

1. 分析实现过程#

因为我采用的是免费方案，Umami Cloud这个是免费，因此不能新建一个用户，同时博客部署都是采用免费方案。
为了稍微安全一点，不建议采用Umami Cloud账号登录
当然如果只是用于测试，那么无所谓啦~

image-20250916235617225

注意这里的 IrVVYJ4qc2J3tc7s ，每个站点都不一样

接着我们请求 https://us.umami.is/api/share/IrVVYJ4qc2J3tc7s，得到token和 websiteId

这个是2025年10月12日修改的，直接采用官网的，之前的方案不能用了

接着我们请求https://cloud.umami.is/analytics/us/api/share/IrVVYJ4qc2J3tc7s，得到token和websiteId

账号token和websiteId

1
{
2
    "websiteId": "77083547-4c2e-4183-b842-520d9de3d82b",
3
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ3ZWJzaXRlSWQiOiI3NzA4MzU0Ny00YzJlLTQxODMtYjg0Mi01MjBkOWRlM2Q4MmIiLCJpYXQiOjE3NTgwMzgyMzh9.7RNrqCaOvgKYFifvpbmtsZR1ykAETgqqOrPgFUpWtng"
4
}

这个时候可以通过/api/websites/:websiteId/stats 获取网站统计汇总。

image-20250917000714829

携带请求头 x-umami-share-token 值为上一步获得的Token

2.0：每次访问都需要携带token才能正常使用，虽然访问https://us.umami.is/api/share/IrVVYJ4qc2J3tc7s中 x-umami-share-token是undefined，但是需要数据的请求都是有值的，
3.0：现在请求链接：https://cloud.umami.is/analytics/us/share/i6f3UwPY4n0w1LJa

image-20250917001706410

最新的Umami数据API

1
https://us.umami.is/api/websites/77083547-4c2e-4183-b842-520d9de3d82b/stats?startAt=0&endAt=1757937599999&unit=hour&timezone=Asia/Hong_Kong&url=/posts/cf-fastip/&compare=false
2

3

4
https://cloud.umami.is/analytics/us/api/websites/77083547-4c2e-4183-b842-520d9de3d82b/stats?startAt=0&endAt=1757937599999&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;

这里解释几个关键Params，其他的照搬

startAt：统计开始时间。Unix时间戳，我们填写为0让Umami从1970年开始统计
endAt：统计结束时间。Unix时间戳，我们可以使用 Date.now() ，即当前时间，和startAt参数联动即可实现统计总浏览量
url（弃用）：要查询的路径，填写为你的文章页去除了Host的路径，如 /posts/hello 。注意！Umami会将 /posts/hello 和 /posts/hello/ 视为两个不同的路径，请注意你的博客框架是否使用 /
path=eq.：通过 path 参数配合 eq. 前缀（表示 “等于”）筛选路径，这是 Umami 支持的 “高级筛选语法”（类似 SQL 的条件表达式），功能上与 url 参数等效，但格式更规范（支持更多条件如 contains 包含、ne 不等于等）。

你会得到

浏览统计展开收起

1
// Umami2.0版本
2
{
3
    "pageviews": {
4
        "value": 26,
5
        "prev": 0
6
    },
7
    "visitors": {
8
        "value": 5,
9
        "prev": 0
10
    },
11
    "visits": {
12
        "value": 9,
13
        "prev": 0
14
    },
15
    "bounces": {
16
        "value": 3,
17
        "prev": 0
18
    },
19
    "totaltime": {
20
        "value": 2885,
21
        "prev": 0
22
    }
23
}
24

25
// Umami3.0版本
26

27
{
28
    "pageviews": 125,
29
    "visitors": 2,
30
    "visits": 4,
31
    "bounces": 1,
32
    "totaltime": 5713,
33
    "comparison": {
34
        "pageviews": 0,
35
        "visitors": 0,
36
        "visits": 0,
37
        "bounces": 0,
38
        "totaltime": 0
39
    }
40
}

展开收起

2.0版本：pageviews.vlaue 即浏览量。 visits.value 即访问次数。

3.0版本：pageviews 即浏览量。 visits 即访问次数。

Tips：浏览量记录为任意用户只要访问了则计数一次。而访问数记录不会记录单IP多次重复访问和同一时间段的多次请求不同页面

2. 代码展示#

src\config.ts中增加UmamiConfig 和 statsConfig

src\config.ts UmamiConfig 和 statsConfig展开收起

1
export const umamiConfig: UmamiConfig = {
2
  enable: true,
3
  baseUrl: "https://us.umami.is",
4
    baseUrl: "https://cloud.umami.is",
5
  shareId: "IrVVYJ4qc2J3tc7s",
6
  timezone: "Asia/Shanghai",
7
};
8

9
export const statsConfig = {
10
  viewsText: "浏览量",
11
  visitsText: "访客",
12
  loadingText: "统计加载中...",
13
  unavailableText: "统计不可用。",
14
  getStatsText: (pageViews: number, visits: number) =>
15
    `${statsConfig.viewsText} ${pageViews} · ${statsConfig.visitsText} ${visits}`,
16
};

展开收起

src\types\config.ts配置UmamiConfig类别

src\types\config.ts

1
export type UmamiConfig = {
2
  enable: boolean;
3
  baseUrl: string;
4
  shareId: string;
5
  timezone: string;
6
};

新增public\js\umami-share.js

public\js\umami-share.js展开收起

1
((global) => {
2
  const cacheKey = "umami-share-cache";
3
  const cacheTTL = 3600_000; // 1h
4

5
  async function fetchShareData(baseUrl, shareId) {
6
    const cached = localStorage.getItem(cacheKey);
7
    if (cached) {
8
      try {
9
        const parsed = JSON.parse(cached);
10
        if (Date.now() - parsed.timestamp < cacheTTL) {
11
          return parsed.value;
12
        }
13
      } catch {
14
        localStorage.removeItem(cacheKey);
15
      }
16
    }
17
    const res = await fetch(`${baseUrl}/api/share/${shareId}`);
18
        const res = await fetch(`${baseUrl}/analytics/us/api/share/${shareId}`);
19
    if (!res.ok) {
20
      throw new Error("获取 Umami 分享信息失败");
21
    }
22
    const data = await res.json();
23
    localStorage.setItem(
24
      cacheKey,
25
      JSON.stringify({ timestamp: Date.now(), value: data }),
26
    );
27
    return data;
28
  }
29

30
  /**
31
   * 获取 Umami 分享数据（websiteId、token）
32
   * 在缓存 TTL 内复用；并用全局 Promise 避免并发请求
33
   * @param {string} baseUrl
34
   * @param {string} shareId
35
   * @returns {Promise<{websiteId: string, token: string}>}
36
   */
37
  global.getUmamiShareData = (baseUrl, shareId) => {
38
    if (!global.__umamiSharePromise) {
39
      global.__umamiSharePromise = fetchShareData(baseUrl, shareId).catch(
40
        (err) => {
41
          delete global.__umamiSharePromise;
42
          throw err;
43
        },
44
      );
45
    }
46
    return global.__umamiSharePromise;
47
  };
48

49
  global.clearUmamiShareCache = () => {
50
    localStorage.removeItem(cacheKey);
51
    delete global.__umamiSharePromise;
52
  };
53
})(window);

展开收起

文章页面src\components\PostMeta.astro增加显示浏览量

image-20250917005701565

src\components\PostMeta.astro展开收起

1
import { Icon } from "astro-icon/components";
2
// 导入statsConfig, umamiConfig配置
3
import { statsConfig, umamiConfig } from "../config";
4
import I18nKey from "../i18n/i18nKey";
5
import { i18n } from "../i18n/translation";
6
import { formatDateToYYYYMMDD } from "../utils/date-utils";
7
import { getCategoryUrl, getTagUrl } from "../utils/url-utils";
8

9
interface Props {
10
  class: string;
11
  published: Date;
12
  updated?: Date;
13
  tags: string[];
14
  category: string | null;
15
  hideTagsForMobile?: boolean;
16
  hideUpdateDate?: boolean;
17
    //当前页面
18
  slug?: string;
19
}
20
const {
21
  published,
22
  updated,
23
  tags,
24
  category,
25
  hideTagsForMobile = false,
26
  hideUpdateDate = false,
27
    //当前页面
28
  slug,
29
} = Astro.props;
30
const className = Astro.props.class;
31

32

33
--------------------------------------------------------------------------------------------
34

35
<!-- page views / 页面显示 -->
36
    {slug && (
37
        <div class="flex items-center">
38
            <div class="meta-icon">
39
                <Icon name="material-symbols:visibility-outline-rounded" class="text-xl"></Icon>
40
            </div>
41
            <span class="text-50 text-sm font-medium" id="page-views-display">{statsConfig.loadingText}</span>
42
        </div>
43
    )}
44
</div>
45

46
--------------------------------------------------------------------------------------------
47
{slug && (
48
    <script define:vars={{ slug, umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
49
        // 客户端统计文案生成函数
50
        function generateStatsText(pageViews, visits) {
51
            return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
52
        }
53

54
        // 获取访问量统计
55
        async function fetchPageViews(isRetry = false) {
56
            if (!umamiConfig.enable) {
57
                return;
58
            }
59

60
            try {
61
                // 调用全局工具获取 Umami 分享数据
62
                const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
63

64
                // 第二步：获取统计数据
65
                const currentTimestamp = Date.now();
66
                const statsUrl = `${umamiConfig.baseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&url=%2Fposts%2F${slug}%2F&compare=false`;
67

68
                const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;
69

70

71
                const statsResponse = await fetch(statsUrl, {
72
                    headers: {
73
                        'x-umami-share-token': token
74
                    }
75
                });
76

77
                if (!statsResponse.ok) {
78
                    if (statsResponse.status === 401 && !isRetry) {
79
                        clearUmamiShareCache();
80
                        return fetchPageViews(true);
81
                    }
82
                    throw new Error('获取统计数据失败');
83
                }
84

85
                const statsData = await statsResponse.json();
86
                const pageViews = statsData.pageviews?.value || 0;
87
                const visits = statsData.visits?.value || 0;
88
                const pageViews = statsData.pageviews || 0;
89
                const visits = statsData.visits || 0;
90

91
                const displayElement = document.getElementById('page-views-display');
92
                if (displayElement) {
93
                    displayElement.textContent = generateStatsText(pageViews, visits);
94
                }
95
            } catch (error) {
96
                console.error('Error fetching page views:', error);
97
                const displayElement = document.getElementById('page-views-display');
98
                if (displayElement) {
99
                    displayElement.textContent = unavailableText;
100
                }
101
            }
102
        }
103

104
        // 页面加载完成后获取统计数据
105
        if (document.readyState === 'loading') {
106
            document.addEventListener('DOMContentLoaded', fetchPageViews);
107
        } else {
108
            fetchPageViews();
109
        }
110
    </script>
111
)}

展开收起

首页卡片文章src\components\PostCard.astro 增加显示浏览量

image-20250917005643777

src\components\PostCard.astro展开收起

1
import { statsConfig, umamiConfig } from "../config";
2

3
--------------------------------------------------------------------------------------------
4

5
<!-- word count and read time and 浏览量 -->
6
        <div class="text-sm text-black/30 dark:text-white/30 flex gap-4 transition">
7
            <div>
8
                {remarkPluginFrontmatter.words} {" " + i18n(remarkPluginFrontmatter.words === 1 ? I18nKey.wordCount : I18nKey.wordsCount)}
9
            </div>
10
            <div>|</div>
11
            <div>
12
                {remarkPluginFrontmatter.minutes} {" " + i18n(remarkPluginFrontmatter.minutes === 1 ? I18nKey.minuteCount : I18nKey.minutesCount)}
13
            </div>
14
            <div>|</div>
15
            <div>
16
                <span class="text-50 text-sm font-medium" id={`page-views-${entry.slug}`}>{statsConfig.loadingText}</span>
17
            </div>
18
        </div>
19

20
--------------------------------------------------------------------------------------------
21
<script define:vars={{ entry, umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
22
    // 客户端统计文案生成函数
23
    function generateStatsText(pageViews, visits) {
24
        return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
25
    }
26

27
    // 获取文章浏览量统计
28
    async function fetchPostCardViews(slug) {
29
        if (!umamiConfig.enable) {
30
            return;
31
        }
32

33
        try {
34
            // 调用全局工具获取 Umami 分享数据
35
            const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
36

37
            // 第二步：获取统计数据
38
            const currentTimestamp = Date.now();
39
            const statsUrl = `${umamiConfig.baseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&url=%2Fposts%2F${slug}%2F&compare=false`;
40

41
            const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&path=eq.%2Fposts%2F${slug}%2F&compare=false`;
42

43
            const statsResponse = await fetch(statsUrl, {
44
                headers: {
45
                    'x-umami-share-token': token
46
                }
47
            });
48

49
            if (statsResponse.status === 401) {
50
                clearUmamiShareCache();
51
                return await fetchPostCardViews(slug);
52
            }
53

54
            if (!statsResponse.ok) {
55
                throw new Error('获取统计数据失败');
56
            }
57

58
            const statsData = await statsResponse.json();
59
            const pageViews = statsData.pageviews?.value || 0;
60
            const visits = statsData.visits?.value || 0;
61

62
            const pageViews = statsData.pageviews || 0;
63
            const visits = statsData.visits || 0;
64
            const displayElement = document.getElementById(`page-views-${slug}`);
65
             if (displayElement) {
66
                 displayElement.textContent = generateStatsText(pageViews, visits);
67
             }
68
        } catch (error) {
69
            console.error('Error fetching page views for', slug, ':', error);
70
            const displayElement = document.getElementById(`page-views-${slug}`);
71
            if (displayElement) {
72
                displayElement.textContent = unavailableText;
73
            }
74
        }
75
    }
76

77
    // 页面加载完成后获取统计数据
78
    function initPostCardStats() {
79
        const slug = entry.slug;
80
        if (slug) {
81
            fetchPostCardViews(slug);
82
        }
83
    }
84

85
    if (document.readyState === 'loading') {
86
        document.addEventListener('DOMContentLoaded', initPostCardStats);
87
    } else {
88
        initPostCardStats();
89
    }
90
</script>
91
<style define:vars={{coverWidth}}>
92
</style>

展开收起

显示总的浏览量src\components\widget\Profile.astro

image-20250917005622652

src\components\widget\Profile.astro展开收起

1
import { profileConfig, statsConfig, umamiConfig } from "../../config";
2

3
--------------------------------------------------------------------------------------------
4

5
 <!-- 全站访问量统计 -->
6
         <div class="text-center text-sm text-neutral-500 dark:text-neutral-400 mt-3 pt-3 border-t border-neutral-200 dark:border-neutral-700">
7
            <div class="flex items-center justify-center gap-1">
8
                <Icon name="material-symbols:visibility-outline" class="text-base"></Icon>
9
                <span id="site-stats">{statsConfig.loadingText}</span>
10
            </div>
11
        </div>
12

13
--------------------------------------------------------------------------------------------
14

15
<script define:vars={{ umamiConfig, unavailableText: statsConfig.unavailableText, viewsText: statsConfig.viewsText, visitsText: statsConfig.visitsText }}>
16
    // 获取全站访问量统计
17
    // 客户端统计文案生成函数
18
    function generateStatsText(pageViews, visits) {
19
        return `${viewsText} ${pageViews} · ${visitsText} ${visits}`;
20
    }
21

22
    async function loadSiteStats() {
23
        if (!umamiConfig.enable) {
24
            return;
25
        }
26

27
        try {
28
            // 调用全局工具获取 Umami 分享数据
29
            const { websiteId, token } = await getUmamiShareData(umamiConfig.baseUrl, umamiConfig.shareId);
30

31
            // 第二步：获取全站统计数据（不指定url参数获取全站数据）
32
            const currentTimestamp = Date.now();
33
            const statsUrl = `${umamiConfig.baseUrl}/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&compare=false`;
34

35
            const statsUrl = `${umamiConfig.baseUrl}/analytics/us/api/websites/${websiteId}/stats?startAt=0&endAt=${currentTimestamp}&unit=hour&timezone=${encodeURIComponent(umamiConfig.timezone)}&compare=false`;
36

37

38
            const statsResponse = await fetch(statsUrl, {
39
                 headers: {
40
                     'x-umami-share-token': token
41
                 }
42
             });
43

44
            if (statsResponse.status === 401) {
45
                // token 失效，清理缓存后重新获取一次
46
                clearUmamiShareCache();
47
                return await loadSiteStats();
48
            }
49

50
            if (!statsResponse.ok) {
51
                throw new Error('获取统计数据失败');
52
            }
53

54
            const statsData = await statsResponse.json();
55
            const pageviews = statsData.pageviews?.value || 0;
56
            const visitors = statsData.visits?.value || 0;
57

58
            const pageviews = statsData.pageviews || 0;
59
            const visitors = statsData.visits || 0;
60

61
            const statsElement = document.getElementById('site-stats');
62
            if (statsElement) {
63
                statsElement.textContent = generateStatsText(pageviews, visitors);
64
            }
65
        } catch (error) {
66
            console.error('获取全站统计失败:', error);
67
            const statsElement = document.getElementById('site-stats');
68
            if (statsElement) {
69
                statsElement.textContent = unavailableText;
70
            }
71
        }
72
    }
73

74
    // 页面加载完成后获取统计数据
75
    document.addEventListener('DOMContentLoaded', loadSiteStats);
76
</script>

展开收起

3. 代码引用#

src\layouts\Layout.astro展开收起

1
<!DOCTYPE html>
2
<html lang={siteLang} class="bg-[var(--page-bg)] transition text-[14px] md:text-[16px]"
3
    data-overlayscrollbars-initialize
4
>
5
  <head>
6

7
    <title>{pageTitle}</title>
8
    // ....
9
    <script defer src="https://cloud.umami.is/script.js" data-website-id="f11536ad-eac1-434b-a0c7-fc78faa63405"></script>
10
    <script src="/js/umami-share.js" defer></script>
11
    {favicons.map(favicon => (
12
      <link rel="icon"
13
          href={favicon.src.startsWith('/') ? url(favicon.src) : favicon.src}
14
          sizes={favicon.sizes}
15
          media={favicon.theme && `(prefers-color-scheme: ${favicon.theme})`}
16
      />
17
    ))}

展开收起

Markdown Extended Features

Wed, 01 May 2024 00:00:00 GMT

GitHub Repository Cards#

You can add dynamic cards that link to GitHub repositories, on page load, the repository information is pulled from the GitHub API.

Fabrizz

MMM-OnSpotify