Hexo配置域名后访问不了,根本原因通常出在DNS解析生效、CNAME文件丢失或CDN缓存这三大环节,按顺序排查即可解决。
hexo绑定域名后打不开,先从解析设置排查
域名打不开,十有八九是解析没设置对,很多人绑完域名刷新半天还是打不开,就开始怀疑是不是Hexo出问题了,Hexo本身只是个静态博客生成器,它不负责域名解析,所有域名访问都要先通过DNS把域名指向服务器IP。
解析类型选错是常见原因
登录你的域名注册商控制台,找到DNS解析设置,这里要确认两件事。
第一,解析类型对不对,GitHub Pages和Gitee Pages要求的是CNAME记录,不是A记录,如果你用的是A记录指向某个IP,那肯定打不开,CNAME记录的记录值要填你的博客默认地址,比如你的用户名.github.io,注意后面不加斜杠。
第二,主机记录填没填对,如果你想用blog.example.com访问,主机记录填blog;想用www.example.com访问,填www;想直接绕开www用主域名访问,填,填错任何一个,都等于白配。
DNS生效时间比你想的要长
设置完解析后,别急着刷新,DNS生效时间在不同地区、不同运营商差异很大,短则几分钟,长则24到48小时,你可以用ping命令测试,在命令行输入ping 你的域名,如果返回的IP是你解析目标服务器的IP,说明解析已经通了,如果返回的是找不到主机或者超时,说明还在等待传播。
行业共识认为,解析设置完成后静置半小时再测试比较合理,期间不要反复修改,每改一次生效时间就要重新计算。
本地hexo博客配置域名访问的关键步骤
很多人以为解析设置完就万事大吉,结果打开GitHub Pages页面发现样式全丢了,或者显示404,问题出在本地配置文件没同步好。
CNAME文件必须放到source目录
这是最容易被忽略的一步,在Hexo项目的source目录下创建一个名为CNAME的文件,注意没有任何后缀名,文件内容只写一行你的域名,比如blog.example.com,保存后重新部署。
这个文件的作用是告诉GitHub Pages你要绑定的域名,它会自动写入到部署后的根目录,很多人直接在public目录里创建CNAME,但hexo clean一下就被清空了,所以必须放在source目录里才能被保留。
_config.yml配置文件有讲究
打开Hexo根目录的_config.yml,找到url字段,改成你的完整域名,格式是https://你的域名,末尾不要加斜杠,同时把root字段保持为,如果你用的是GitHub Pages,还需要把deploy配置里的repo地址确认好,分支通常是main或master,视你的仓库设置而定。
修改完执行hexo clean && hexo g -d,重新生成并部署,这一步必须做,因为url字段直接影响所有文章链接的生成,不修改的话页面能打开但内部链接全是指向localhost或者旧地址的。
本地预览和线上不一致怎么办
本地跑hexo server预览通常是正常的,因为本地服务器会直接读取public目录,但线上访问是走GitHub Pages或Gitee Pages的CDN节点,存在缓存延迟,执行部署命令后等一两分钟再刷新,如果还是打不开,用无痕模式访问一次,排除浏览器缓存干扰。
GitHub Pages自定义域名404的排查路径
GitHub Pages是Hexo用户最常用的托管平台,它的404问题有自己的特殊性。
仓库设置里的Custom domain必须填
打开你的GitHub仓库,进入Settings页面,往下找到Pages选项,在Custom domain输入框里填上你的域名,点击Save,这一步会触发GitHub自动创建CNAME文件到仓库里,同时你的CNAME文件也会在下次部署时被带到线上。
如果保存后提示Domain is not recognized,说明DNS解析还没生效,GitHub无法验证域名所有权,等解析生效后重新保存即可。
HTTPS证书申请失败的原因
GitHub Pages自动签发HTTPS证书需要时间,通常几分钟到几小时不等,如果等待较长时间后仍显示Certificate is being created,多数原因是你的域名之前绑定过其他服务,证书缓存没清理干净,在Settings里取消勾选Enforce HTTPS,保存后重新勾选,强制重新签发。
据统计,自定义域名在GitHub Pages上的HTTPS签发失败,多数情况都和DNS解析记录中同时存在多条互相矛盾的记录有关,检查一下有没有残留的AAAA记录或者多余的TXT记录,清理干净后等证书签发。
Gitee Pages域名访问不了的特殊处理
国内用户用Gitee Pages的也不少,但它和GitHub Pages在域名绑定上有明显差异。
Gitee要求实名认证和手动触发
Gitee Pages的自定义域名功能默认不开放,需要在Gitee Pages服务页面点击“开通”并完成实名认证,部署也不是自动的,每次代码推送后都要登录Gitee Pages后台,点击“更新”按钮手动发布。
国内服务器备案要求可能卡住你
据Gitee官方说明,使用Gitee Pages绑定的自定义域名,如果服务节点在国内,域名必须完成ICP备案,未备案的域名绑定后会直接无法访问,如果你没有备案,要么更换国内的托管服务,要么把博客迁回GitHub Pages,要么使用Cloudflare Workers等境外方案。
对比一下主流托管平台的访问差异
| 托管平台 | 自定义域名支持 | 国内访问速度 | 是否需要备案 | 部署方式 |
|---|---|---|---|---|
| GitHub Pages | 支持 | 不稳定,偶尔被墙 | 不需要 | 推送代码自动部署 |
| Gitee Pages | 支持 | 快 | 需要ICP备案 | 手动点击更新 |
| Cloudflare Pages | 支持 | 取决于网络 | 不需要 | 推送代码自动部署 |
一套顺序排查法解决绝大多数访问故障
如果按上面步骤操作完还是打不开,不要反复修改配置,按以下顺序逐项排查。
从外到内逐层验证
第一步,先用ping 你的域名确认解析是否到达预期IP,如果超时,问题出在DNS层面,如果通了,继续下一步。
第二步,直接访问IP地址,看是否返回站点内容,如果返回404或无法访问,说明服务器本身有问题。
第三步,本地执行curl -I 你的域名,查看返回的HTTP状态码,200表示正常,301/302表示重定向配置有问题,404表示路径不对。
最常见的两个低级失误
一是域名买了但没实名认证,很多新注册域名必须在注册商处完成实名审核才能正常解析,审核通常需要1到3个工作日,查一下你的域名状态是否显示ServerHold,如果是,说明被注册局暂停解析了。
二是忘了续费,域名过期后会被注册商停止解析,这种情况下什么配置都没用,检查邮箱有没有收到续费提醒,或者直接登录注册商控制台看域名到期时间。
重定向导致样式丢失的处理
如果你用hexo-abbrlink之类的插件生成了永久链接,改域名后旧链接全部失效,在此之前,建议先配置从旧地址到新地址的301跳转,避免搜索引擎收录的旧链接全部变成死链,处理方式是修改Nginx配置或GitHub Pages的_redirects文件,将旧路径统一重定向到新域名的对应路径。
关于hexo域名访问不了常见疑问解答
Hexo配置了CNAME但GitHub Pages不生效是什么原因?
GitHub Pages的Custom domain设置和源码仓库里的CNAME文件必须同时存在,如果只添加了CNAME文件但没在仓库Settings里填写Custom domain,或者填写了但没点击Save,GitHub不会识别你的自定义域名,填写保存后等待证书签发,再访问即可。
Hexo域名解析设置完成后需要等多久才能访问?
DNS解析的生效时间受本地ISP缓存和根服务器刷新周期影响,同一时间在不同地区测试结果可能完全不同,设置完成后建议等待30分钟,然后用全局DNS检测工具查看各国解析状态,如果全部生效且返回正确的IP,但浏览器依然无法访问,检查本地电脑的DNS缓存,命令行执行ipconfig/flushdns清空后重启浏览器。
主域名带www和不带www哪种方式更适合博客访问?
两种方式在实现原理上没有区别,但存在一个是否便于记忆的差异,不带www的主域名需要额外的裸域解析支持,部分小型域名注册商对裸域解析的稳定性不如二级域名,如果你的域名服务商支持,设置一个从带www到不带www的301跳转即可,用户访问任意一种形式都能自动到达你的博客,搜索引擎也会统一收录权重到主域名上。