这套博客搭建过程并非一路顺畅，这一篇如实记录几个真实踩过的坑，以及最终的解决方案，希望能帮后来者少走弯路。

坑一：域名没解析好之前，静态资源路径全错

刚部署上线时，通过 GitHub 默认分配的临时地址（https://用户名.github.io/仓库名/）访问，发现整个页面 CSS/JS 全部加载失败，页面”裸奔”成了一堆无样式的文字列表。

原因：Hexo 站点配置里的 url 字段如果写死成最终域名（比如 https://linfei.wang），但实际访问路径带有仓库名前缀（/仓库名/），所有资源引用路径就会对不上。

解决：域名解析生效之前，先把 url 临时改成实际的 GitHub Pages 项目路径，并设置对应的 root 字段：

1
2
url: https://用户名.github.io/仓库名
root: /仓库名/

等域名解析和 GitHub Pages 绑定都完成之后，再切回正式域名配置：

1
2
url: https://linfei.wang
root: /

坑二：Cloudflare Workers 的 workers.dev 域名国内访问不稳定

一开始选择 Cloudflare Workers 做 AI 聊天机器人的反向代理，配置全部完成、密钥也设置好了，但前端调用时频繁出现连接失败、SSL 握手错误。排查后发现这是国内网络环境访问 *.workers.dev 域名的老问题（DNS 解析经常被干扰），不是配置错误。

尝试的补救方案：给 Worker 绑定自定义子域名（比如 chat.linfei.wang），走自己的域名解析。但操作过程中”Add Domain”这一步反复卡住、没有成功生成 NS 记录提示，多次重试都没能走通。

最终决定：既然已经在腾讯云买了域名，干脆换用**腾讯云函数（SCF）**做这个反向代理，同一账号体系，国内节点原生访问，不存在跨境网络问题。这也是这个系列里”技术选型要考虑实际网络环境”的一个真实案例。

坑三：腾讯云 API 网关触发器已经下线

按照旧教程配置腾讯云函数时，创建触发器环节找不到”API网关触发器”选项，页面提示：

由于API网关产品于2025年6月30日停止服务，新老用户均不再支持新建API网关触发器

解决：改用腾讯云新推出的**「函数URL」**功能替代 —— 直接给函数分配一个永久固定的公网 HTTP(S) 端点，不需要额外配置网关层，操作路径是：函数详情页 → 左侧「函数 URL」→「新建函数 URL」→ 开启公网访问 + 授权类型选”开放/免鉴权”。

坑四：函数文件后缀 .mjs vs .js 的坑

腾讯云函数在线编辑器默认生成的文件是 index.mjs，但我写的云函数代码是 CommonJS 格式（用 require() 和 exports.main_handler），跟 .mjs（ES Module 格式）语法不兼容，会直接报错。

解决：把文件重命名为 index.js（去掉 m），代码就能正常识别和运行了。

坑五：函数执行超时时间设置过短

云函数默认的”执行超时时间”配置只有 3 秒，而调用大模型 API 通常需要几秒到十几秒才能返回结果，导致函数频繁超时报错。

解决：在函数「函数配置」里把执行超时时间调整为 30 秒（范围支持1-900秒），完全覆盖大模型响应耗时的正常区间。

坑六：环境变量改了没生效

修改环境变量（存放 API Key）后立即测试，报错”令牌已过期或验证不正确”，但直接用同一个 Key 单独测试大模型接口却完全正常。

原因：忘了点保存按钮，配置改动没有真正提交生效。

解决：仔细确认每次改动配置后都点了保存/确定，必要时刷新页面重新检查配置是否真的写入。

坑七：图片体积过大导致首屏加载慢

首页的顶部背景图和头像图都是用 AI 生成的高清图片，单张体积高达 1.2MB-1.4MB，直接导致首次打开页面时背景图要等很久才渐显出来。

解决：用 Mac 自带的 sips 命令行工具批量压缩：

1
sips -s format jpeg -s formatOptions 65 -Z 1600 top-cover.jpg --out top-cover-new.jpg

限制最大尺寸（背景图1600px宽）并设置合理的 JPEG 压缩质量（65-75），最终把两张图从共2.6MB压缩到约250KB，压缩率超过90%，网页展示画质几乎没有肉眼可辨的损失。

写在最后

回顾整个搭建过程，真正耗时最长的反而不是”写代码”，而是排查各种平台的产品变更、网络环境差异、配置细节疏漏。这也是我想把这些坑记录下来的原因——技术学习的价值往往不在于代码本身有多复杂，而在于遇到问题时能不能耐心排查、找到根因、找到可行的替代方案。这份耐心和解决问题的能力，我想，同样也是求职时希望展示给HR的一种素质。

这个系列就先写到这里，如果搭建过程中遇到新的问题或者优化点，我会继续更新。欢迎通过右下角的AI聊天框和我交流具体细节。