Typecho博客使用阿里云cdn和oss：handsome主題進階版

Typecho使用阿里云cdn和oss

- - 設置前需要保證阿里云cdn和oss已配置好且可以正常使用
  - 一、準備工作
  - 二、修改 Handsome 主題的靜態資源鏈接
  - - 方法 1：直接修改主題文件（推薦）
    - 方法 2：通過主題設置自定義（方便）
  - 三、處理特殊資源
  - - 1. 字體文件（如 .woff2）
    - 2. 懶加載占位圖
  - 四、驗證與調試
  - 五、使用typecho插件自動上傳文件
  - 六、備份與回滾
  - 六、自動化同步（可選）
  - 七、常見問題
  - - Q1：修改后頁面布局錯亂
    - Q2：CDN 緩存未更新
  - 八、常見錯誤分析與解決（補充）
  - - 問題：資源404錯誤
    - 問題：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，查找類似代碼：

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

修改為絕對路徑，指向 OSS 地址：

<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 后添加版本號，強制瀏覽器刷新緩存：

<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 文件中：

/* 原代碼 */
@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 工具同步：

# 將本地主題資源實時同步到 OSS
ossutil sync -u /www/wwwroot/blog.ybyq.wang/usr/themes/handsome/ oss://blog-static-ybyq/usr/themes/handsome/ --delete

寶塔面板定時任務：

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

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，添加版本參數強制瀏覽器獲取新版本：

<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格式
基本格式應類似：

{"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"
}