# FriendLinks

**Repository Path**: ilogs/friend-links

## Basic Information

- **Project Name**: FriendLinks
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-08-12
- **Last Updated**: 2026-08-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# FriendLinks

FriendLinks 是一款简洁的 Typecho 友情链接管理插件，提供后台管理、状态筛选、搜索分页，以及可直接写入文章或独立页面的友情链接短代码。

## 功能

- 友情链接新增、编辑、隐藏、黑名单和销毁
- 后台按昵称、站名、网址或邮箱搜索
- 后台状态筛选与分页
- `[friendlinks]` 短代码输出响应式友链卡片
- 自定义头像服务地址，支持邮箱 MD5 与头像尺寸占位符
- 支持为单个友链上传 JPG、PNG、GIF、WebP 或 ICO 头像
- 未配置头像服务且未上传头像时，自动缓存友链网站的 `/favicon.ico`
- 浅蓝、浅粉、浅绿、浅紫、浅橘、浅灰六种卡片配色
- 仅在检测到短代码的页面注入前台样式
- 停用插件时保留已有友链数据

## 环境要求

- Typecho 1.2 或更高版本
- PHP 7.4 或更高版本
- MySQL / MariaDB

## 安装

1. 下载或克隆本项目。
2. **必须将插件目录重命名为 `FriendLinks`，大小写必须完全一致。** Gitee 下载得到的 `friend-links`、`friend-links-master` 等目录名不能直接启用。
3. 把整个目录放入 Typecho 的 `usr/plugins/`：

   ```text
   usr/plugins/FriendLinks/
   ├── Plugin.php
   └── Manage.php
   ```

   请同时确认没有形成 `usr/plugins/FriendLinks/FriendLinks/Plugin.php` 这样的双层目录。

4. 登录 Typecho 后台，在“控制台 → 插件”中启用 FriendLinks。
5. 启用后，在“控制台 → 友链管理”中维护数据。

详细说明请参阅 [使用文档](docs/usage.md)。

## 常见故障

如果前台出现以下警告：

```text
class 'FriendLinks_Plugin' not found
```

说明 Typecho 已保存插件回调，但无法从规定路径加载插件类。请确认服务器上的入口文件严格位于：

```text
usr/plugins/FriendLinks/Plugin.php
```

修正目录后，到 Typecho 后台停用并重新启用 FriendLinks，以刷新插件回调。更多处理方法参阅 [故障排查](docs/troubleshooting.md)。

## 短代码

在文章或独立页面正文中单独写入：

```text
[friendlinks]
```

默认显示状态为 `1` 的正常友联。还可以指定状态：

```text
[friendlinks status="3"]
```

状态定义：

| 值 | 含义 | 前台默认展示 |
|---:|---|---|
| 0 | 隐藏 | 否 |
| 1 | 正常友联 | 是 |
| 3 | 黑名单 | 否 |

## 头像服务

头像服务默认为空。未配置服务时，插件使用自带的本地默认头像，不会请求开发者或其他第三方头像服务器。

如需使用自己的头像服务，可填写类似：

```text
https://example.com/avatar/{md5}?s={size}
```

- `{md5}`：友链邮箱的小写 MD5
- `{size}`：请求的头像尺寸

请将示例域名替换为你有权使用的服务地址。

头像显示优先级为：上传头像 → 后台头像服务生成的邮箱 MD5 头像 → 网站 favicon 本地缓存 → 插件内置头像。

当头像服务地址留空且友链没有上传头像时，插件会尝试读取该网站根目录的 `/favicon.ico`，验证为有效图片后缓存到：

```text
usr/uploads/friendlinks/favicon/
```

已有缓存会在页面输出时直接使用，不再发起请求。没有缓存且不处于失败冷却期的友链，才由浏览器按顺序逐个请求插件接口：前一个处理完成后才会请求下一个。任何获取失败都会记录 24 小时，PHP 与浏览器都会在冷却期内跳过该友链；站点级文件锁也会阻止多个访客并发重复下载。

## 隐私说明

插件前台不会输出友链邮箱明文，但头像地址会包含邮箱 MD5。MD5 并非加密算法，若攻击者持有候选邮箱列表，理论上可以进行匹配。对隐私要求较高时，请使用不依赖邮箱 MD5 的头像方案。

## 开发者

- 开发者：ilogs 全局变量
- 主页：[https://ilogs.cn](https://ilogs.cn)
- 仓库：[https://gitee.com/ilogs/friend-links](https://gitee.com/ilogs/friend-links)
- QQ 群：1091754579

## 许可证

本项目使用 [MIT License](LICENSE) 开源。