Typecho博客使用阿里云cdn和oss：handsome主题进阶版

Typecho使用阿里云cdn和oss

- - 设置前需要保证阿里云cdn和oss已配置好且可以正常使用
  - 一、准备工作
  - [二、修改 Handsome 主题的静态资源链接](#二、修改 Handsome 主题的静态资源链接)
  - - [方法 1：直接修改主题文件（推荐）](#方法 1：直接修改主题文件（推荐）)
    - [方法 2：通过主题设置自定义（方便）](#方法 2：通过主题设置自定义（方便）)
  - 三、处理特殊资源
  - - [1. 字体文件（如 .woff2）](#1. 字体文件（如 .woff2）)
    - [2. 懒加载占位图](#2. 懒加载占位图)
  - 四、验证与调试
  - 五、使用typecho插件自动上传文件
  - 六、备份与回滚
  - 六、自动化同步（可选）
  - 七、常见问题
  - - Q1：修改后页面布局错乱
    - [Q2：CDN 缓存未更新](#Q2：CDN 缓存未更新)
  - 八、常见错误分析与解决（补充）
  - - 问题：资源404错误
    - [问题：OSS 403 Forbidden错误](#问题：OSS 403 Forbidden错误)
    - 问题：CDN缓存与刷新
    - 问题：site.webmanifest语法错误

设置前需要保证阿里云cdn和oss已配置好且可以正常使用

一、准备工作

确认 OSS 资源已同步：
- 将主题的静态资源（CSS/JS/图片/字体）上传到 OSS Bucket，路径与本地保持一致。
  例如：将 /usr/themes/handsome/assets 同步到 OSS 的 /handsome/asserts。
验证 OSS 访问权限：
- 确保通过 https://static.blog.ybyq.wang/handsome/css/style.css 可直接访问文件。

二、修改 Handsome 主题的静态资源链接

方法 1：直接修改主题文件（推荐）

定位资源引用位置 ：

Handsome 主题的静态资源主要在以下文件中定义：
- /usr/themes/handsome/component/header.php：头部 CSS/JS 引用。
- /usr/themes/handsome/component/footer.php：底部 JS 引用。
- /usr/themes/handsome/css/、/js/、/img/ 等目录下的文件。

替换资源域名：

打开 header.php 和 footer.php，查找类似代码：

html 复制代码

<link rel="stylesheet" href="<?php $this->options->themeUrl('css/style.css'); ?>">
<script src="<?php $this->options->themeUrl('js/main.js'); ?>"></script>

修改为绝对路径，指向 OSS 地址：

html 复制代码

<link rel="stylesheet" href="https://static.blog.ybyq.wang/usr/themes/handsome/css/style.css">
<script src="https://static.blog.ybyq.wang/usr/themes/handsome/js/main.js"></script>

版本化控制（可选）：

在 URL 后添加版本号，强制浏览器刷新缓存：

html 复制代码

<link rel="stylesheet" href="https://static.blog.ybyq.wang/usr/themes/handsome/css/style.css?v=20231001">

方法 2：通过主题设置自定义（方便）

利用 Handsome 的 CDN 设置功能 ：
- 登录 Typecho 后台，进入 外观 > Handsome 主题设置 > 基础设置。
- 查找 静态资源 CDN 地址 或 自定义 CSS/JS 链接 选项，填写 OSS 地址：
  复制代码
```
https://static.blog.ybyq.wang/handsome/assets
```
- 保存设置后，主题会自动拼接路径（Handsome主题支持此功能）。

三、处理特殊资源

1. 字体文件（如 .woff2）

修改字体文件路径，通常位于 CSS 文件中：

css 复制代码

/* 原代码 */
@font-face {
  src: url('../fonts/iconfont.woff2') format('woff2');
}

/* 修改后 */
@font-face {
  src: url('https://static.blog.ybyq.wang/usr/themes/handsome/fonts/iconfont.woff2') format('woff2');
}

2. 懒加载占位图

在 主题设置 > 外观设置 > 懒加载 中，将默认占位图替换为 OSS 地址（这个开启后会自动添加）：
复制代码
```
https://static.blog.ybyq.wang/handsome/img/loading.gif
```

四、验证与调试

浏览器开发者工具：
- 打开 https://blog.ybyq.wang，按 F12 进入开发者工具，切换到 Network 选项卡。
- 检查所有 CSS/JS/图片/字体请求是否来自 static.blog.ybyq.wang，状态码为 200 或 304。
强制刷新缓存：
- 按 Ctrl+F5 强制刷新页面，避免本地缓存干扰。
混合内容警告：
- 确保所有 OSS 资源链接为 https://，若存在 http:// 请求，浏览器会提示不安全，需修正为 HTTPS。

五、使用typecho插件自动上传文件

使用插件AliOssForTypecho
插件中的AccessKey在阿里云控制台中创建
在阿里oss建立好usr/uploads/文件夹，使用插件上传后的图片会存储在里面
F5重载网站，检查图片路径是否为阿里云oss的路径

控制台显示，路径为https://static.blog.ybyq.wang/usr/uploads/，引用成功。

六、备份与回滚

备份主题文件 ：
- 修改前，将 /usr/themes/handsome/ 目录整体压缩备份。
快速回滚 ：
- 若修改后页面异常，直接上传备份文件恢复即可。

六、自动化同步（可选）

使用 ossutil 工具同步 ：

bash 复制代码

# 将本地主题资源实时同步到 OSS
ossutil sync -u /www/wwwroot/blog.ybyq.wang/usr/themes/handsome/ oss://blog-static-ybyq/usr/themes/handsome/ --delete

宝塔面板定时任务 ：

添加 Shell 脚本，每天凌晨同步一次：

bash 复制代码

ossutil64 cp -r /www/wwwroot/blog.ybyq.wang/usr/themes/handsome/ oss://blog-static-ybyq/usr/themes/handsome/ --update

使用这种同步方式需保持两边路径相同

七、常见问题

Q1：修改后页面布局错乱

原因：资源路径错误或 OSS 文件未同步。
解决：
1. 检查浏览器控制台报错信息，确认缺失的文件。
2. 核对 OSS 中文件路径是否与代码中的引用一致。
3. 检查目录名字是否正确

Q2：CDN 缓存未更新

解决：在阿里云 CDN 控制台手动刷新对应文件的缓存，或在 URL 后添加版本号（如 ?v=20231002）。

通过以上步骤，Handsome 主题的静态资源将全部通过 OSS + CDN 加速，显著提升加载速度并降低服务器负载。

八、常见错误分析与解决（补充）

问题：资源404错误

错误示例：

复制代码

GET https://blog.ybyq.wang/usr/themes/handsome/assets/js/main.min.js net::ERR_ABORTED 404 (Not Found)
GET https://blog.ybyq.wang/usr/themes/handsome/assets/css/main.min.css net::ERR_ABORTED 404 (Not Found)

解决方法：

路径不一致问题：检查主题设置和OSS中的路径格式是否一致
- 可能存在 /usr/themes/handsome/assets/ 和 /handsome/assets/ 两种不同路径
- 建议统一为一种路径格式，推荐使用与本地相同的完整路径 /usr/themes/handsome/assets/
修改主题设置：
- 进入 Handsome 主题设置 > 基础设置
- 确认"静态资源CDN地址"填写完整路径：https://static.blog.ybyq.wang/usr/themes/handsome
- 如果使用简化路径，确保OSS中的目录结构与之匹配
检查OSS中的文件是否已上传：
- 登录阿里云OSS控制台，确认所有静态资源文件都已正确上传
- 测试直接访问OSS中的文件，例如：https://static.blog.ybyq.wang/usr/themes/handsome/assets/js/main.min.js

问题：OSS 403 Forbidden错误

错误示例：

复制代码

GET https://static.blog.ybyq.wang/handsome/assets/js/features/jquery.pjax.min.js net::ERR_ABORTED 403 (Forbidden)

解决方法：

检查Bucket权限设置：
- 登录OSS控制台
- 选择您的Bucket > 权限管理 > 读写权限
- 确保设置为"公共读"（推荐）或"公共读写"
检查Referer防盗链设置：
- 选择您的Bucket > 权限管理 > 防盗链
- 如果启用了防盗链，确保添加了 blog.ybyq.wang 到白名单
- 或者暂时关闭防盗链测试
检查CORS跨域设置：
- 选择您的Bucket > 权限管理 > 跨域设置
- 添加规则：来源 https://blog.ybyq.wang，允许的方法 GET，允许的头 *

问题：CDN缓存与刷新

当修复问题后，CDN可能仍然提供旧的缓存内容，导致问题持续存在。

解决方法：

手动刷新CDN缓存：
- 登录阿里云CDN控制台
- 选择"刷新预热" > "刷新"
- 添加需要刷新的URL或目录：
  - URL刷新: https://static.blog.ybyq.wang/usr/themes/handsome/assets/js/main.min.js
  - 目录刷新: https://static.blog.ybyq.wang/usr/themes/handsome/

添加版本号：

修改资源引用URL，添加版本参数强制浏览器获取新版本：

html 复制代码

<link rel="stylesheet" href="https://static.blog.ybyq.wang/usr/themes/handsome/assets/css/main.min.css?v=20250428">

问题：site.webmanifest语法错误

错误示例：

复制代码

Manifest: Line: 1, column: 1, Syntax error.

解决方法：

检查webmanifest文件：

在服务器上找到并打开 site.webmanifest 文件
确保是有效的JSON格式
基本格式应类似：

json 复制代码

{
  "name": "博客名称",
  "short_name": "简称",
  "icons": [
    {
      "src": "/icon-192x192.png",
      "sizes": "192x192",
      "type": "image/png"
    },
    {
      "src": "/icon-512x512.png",
      "sizes": "512x512",
      "type": "image/png"
    }
  ],
  "theme_color": "#ffffff",
  "background_color": "#ffffff",
  "display": "standalone"
}

如果不需要此功能，可以在主题中禁用：
- 编辑 /usr/themes/handsome/component/header.php
- 找到引用 site.webmanifest 的行，注释掉或删除

补充说明：如果网站仍然间歇性错乱，建议检查是否存在多个CDN配置冲突，或者是否启用了浏览器缓存（Service Worker）相关功能。有时候需要清除浏览器缓存并强制刷新（Ctrl+F5）来测试最新配置是否生效。

作者：xuan

个人博客：https://blog.ybyq.wang

欢迎访问我的博客，获取更多技术文章和教程。