示例1：下载根目录的”电脑.zip”文件#

示例2：自定义显示名称#

::pan123-file{ path=“/电脑.zip”, name=“我的电脑配置文件”, icon=“material-symbols” }

代码示例：

1
::pan123{path="/电脑.zip"}
2

3
::pan123-file{
4
  path="/电脑.zip",
5
  name="我的电脑配置文件",
6
  icon="material-symbols:computer"
7
}

示例3：内联下载链接#

点击此处下载 [::pan123-link{path=“/电脑.zip”}] 文件，该文件包含了我的电脑配置备份。

或者使用自定义链接文本：[::pan123-link{path=“/电脑.zip” name=“电脑配置备份文件”}]。

代码示例：

1
点击此处下载 [::pan123-link{path="/电脑.zip"}] 文件。
2

3
或者使用自定义链接文本：[::pan123-link{path="/电脑.zip" name="电脑配置备份文件"}]。

文件路径格式#

文件路径必须使用123网盘中的完整路径，以 / 开头：

• /电脑.zip - 根目录下的文件
• /文档/报告.pdf - 子目录中的文件
• /备份/2024/系统镜像.iso - 多级目录中的文件

环境配置#

要使用123网盘功能，需要在环境变量中配置以下信息：

1
PAN123_USERNAME=您的123网盘账号
2
PAN123_PASSWORD=您的123网盘密码
3
PAN123_WEBDAV_URL=https://webdav.123pan.cn/webdav

可选功能：Cloudflare KV缓存#

如需提高性能，可以启用Cloudflare KV缓存：

1
PAN123_USE_KV=true

启用后，文件信息将被缓存1小时，减少对123网盘API的直接调用。

技术实现说明#

本集成采用混合方案C，解决了Astro框架中查询参数可能丢失的问题：

1. 三重请求机制：

   • 首先尝试POST请求（JSON请求体）
   • 其次尝试GET请求（查询参数）
   • 最后尝试路径参数方式

2. API端点优化：

   • 添加 export const prerender = false 避免静态构建问题
   • 支持多种URL格式，确保兼容性

3. 前端智能重试：

   • 组件会自动尝试所有可用方式
   • 提供详细的调试日志
   • 优雅降级处理

不同文件类型#

目录列表（通过API）#

您还可以通过API获取目录列表，支持多种请求方式：

1
GET /api/pan123/info?path=/文档&list=true

1
POST /api/pan123/info
2
Content-Type: application/json
3

4
{
5
  "path": "/文档",
6
  "list": true
7
}

1
GET /api/pan123/info/文档?list=true

核心优势#

1. 多重兼容性：采用混合方案C，支持POST、GET查询参数、路径参数三种请求方式
2. 智能重试：前端组件自动尝试所有可用方式，确保最大兼容性
3. 优雅降级：即使某种方式失败，系统会自动尝试其他方式
4. 详细日志：提供完整的调试信息，便于问题排查

已解决的问题#

• ✅ Astro查询参数丢失：通过混合方案C解决
• ✅ 静态构建问题：添加 export const prerender = false
• ✅ URL构建错误：规范化基础URL和文件路径
• ✅ 认证失败：完善的错误处理和重试机制

立即尝试：在您的文章中使用 ::pan123{path="/您的文件路径"} 语法，体验便捷的文件分享功能！

技术支持#

如需技术支持或报告问题，请参考完整的使用手册：docs/PAN123_INTEGRATION.md