前言

npm install 跑了十分钟还在转圈, 最后报错 ETIMEDOUT 或 ECONNRESET—— 这种事几乎每个国内开发者都遇到过。

网上搜一圈, 会看到各种答案: 换镜像源、清缓存、关SSL、调超时…… 但这些答案大多是碎片化的, 而且有些互相矛盾(比如让你 strict-ssl=false, 这实际上是在关掉安全检查)。

这篇想做的事是: 给一个有序的排查框架, 让你知道每一步在解决什么问题, 而不是照抄命令碰运气。

一、先定位: 你到底遇到的是哪一类问题

不同症状对应不同原因, 乱试只会浪费时间。

先确认你属于哪一类, 再往下看。 这能省掉大半的无效尝试。

三个诊断命令

1
2
3
4
5
6
7
8

# 1. 看当前实际用的源(不要凭记忆, 看实际配置)
npm config get registry

# 2. 测试源是否可达 + 耗时
curl -s -o /dev/null -w "HTTP码: %{http_code} 耗时: %{time_total}s\n" -m 20 https://registry.npmmirror.com/react

# 3. 测试 npm 能不能拿到包元数据
npm view react version

npm view react version 这一条最关键—— 它只取元数据, 不下载 tarball, 所以能最快判断”源本身通不通”。

如果这条命令就卡住或报错, 问题在源和网络, 与项目无关。

二、镜像源: 怎么选, 以及最重要的”失效检测”

常见镜像源现状(2026 年实测)

我在写这篇时实测了各源的状态, 结果如下:

1
2
3
4
5
6
7
8
9
10
11

# 老淘宝源
curl -o /dev/null -w "%{http_code}\n" -m 20 https://registry.npm.taobao.org/react
# 输出: 000  ← 已完全不可用

# npmmirror(淘宝系新域名)
curl -o /dev/null -w "%{http_code}\n" -m 20 https://registry.npmmirror.com/react
# 输出: 200  ← 正常

# 官方源
curl -o /dev/null -w "%{http_code}\n" -m 20 https://registry.npmjs.org/react
# 输出: 200  ← 正常但国内慢

重点: registry.npm.taobao.org 这个老地址已经停止服务。 很多人的 .npmrc 里还留着它(这是几年前的教程留下的习惯), 结果所有 npm 命令都在超时。

如果你现在的 npm config get registry 返回的是 registry.npm.taobao.org, 恭喜你找到了一个大概率就是你现在问题的原因。 直接换成 registry.npmmirror.com 即可。

镜像源对比

建议备 2 个,主源挂了自动切备用。

配置方法

用户级(推荐, 全局生效)

1
2
3

npm config set registry https://registry.npmmirror.com/
npm config get registry
# 确认输出正确

项目级(团队项目建议用这个)

在项目根目录建 .npmrc:

1
2
3
4
5

registry=https://registry.npmmirror.com/
fetch-retries=3
fetch-retry-mintimeout=10000
fetch-retry-maxtimeout=60000
fetch-timeout=120000

项目级优先于用户级, 这样新人 clone 项目后不用配就能用。

检测源是否失效(建议每月做一次)

1
2

# 这个命令返回 000 就说明源挂了
curl -s -o /dev/null -w "%{http_code}\n" -m 15 https://registry.npmmirror.com/react

技巧: 很多”莫名其妙开始变慢”的情况, 都是某个镜像源悄悄挂了或限流了。 养成定期检测的习惯, 或者在 CI 里加一个健康检查。

三、超时相关参数: 该调哪个, 调多少

npm 的四个关键参数

1
2
3
4
5

# 拿到这些值的当前设置
npm config get fetch-retries
npm config get fetch-retry-mintimeout
npm config get fetch-retry-maxtimeout
npm config get fetch-timeout

含义和推荐值:

一次性设好:

1
2
3
4

npm config set fetch-retries 3
npm config set fetch-retry-mintimeout 10000
npm config set fetch-retry-maxtimeout 60000
npm config set fetch-timeout 120000

一条重要的调参原则

不要一上来就疯狂调大超时。 顺序应该是:

1. 先换源(成本最低, 效果最明显)
2. 再调重试参数
3. 最后才考虑加超时

因为如果是源本身有问题, 把超时加到 10 分钟只会让你等得更久才失败。

什么时候该调大超时

• 你在跨洲网络(比如国内访问海外 CI)
• 依赖里有大包(如electron、chromium)
• 你在低带宽环境(公司内网、虚拟机)

这时候可以专门给某个命令加超时:

1

npm install --fetch-timeout=600000

四、DNS 与网络层排查

如果换源后依然超时, 问题可能在更底层。

判断是不是 DNS 问题

1
2
3
4
5

# 测试域名解析
nslookup registry.npmmirror.com

# 测试连接耗时
curl -w "连接耗时: %{time_connect}s  总耗时: %{time_total}s\n" -o /dev/null https://registry.npmmirror.com/react

time_connect 很大(比如超过 1 秒)说明建连本身慢, 可能需要检查网络路径。

换 DNS

Windows:

1
2

# 查看当前 DNS
nslookup | more

如果解析到的 IP 不合理(比如指向了失效的CDN), 可以改成公共 DNS: 223.5.5.5(阿里)、119.29.29.29(腾讯)。

排查是否走代理

这是最容易漏掉的一项。

1
2
3
4
5
6
7

# 看环境变量里有没有代理
echo $HTTP_PROXY
echo $HTTPS_PROXY

# 看 npm 自己配置的代理
npm config get proxy
npm config get https-proxy

代理与镜像源的冲突是个经典坑:

• 代理正常工作时, npm 走代理, 不需要镜像源
• 但如果代理部分失效(比如内网走代理、外网不走), 就会时好时坏
• 更糟的情况: 配置了镜像源 + 代理, 请求可能走了两次转发, 反而更慢

排查方法:

1
2

# 临时禁用代理再试
npm install --no-proxy

如果禁用后变快, 说明问题在代理配置。

五、pnpm: 报错信息完全不同

pnpm 的错误码和 npm 不一样, 而且 pnpm 默认使用严格模式, 一些 npm 下能容忍的问题在 pnpm 下会直接报错。

pnpm 的常见错误

ERR_PNPM_META_FETCH_FAIL

取包元数据失败, 通常是网络或源配置问题。

排查顺序:

1. pnpm config get registry 确认源地址
2. curl 测试该源是否可达
3. 确认没被代理干扰(pnpm config get proxy)

ERR_PNPM_FETCH_404

包在仓库里不存在。 常见于:

• 包名拼错
• 包已unpublish 或改名
• scoped 包在镜像源上缺失(如@myorg/pkg)

ERR_PNPM_NO_MATCHING_VERSION

指定版本不存在。

1
2
3
4

# 查包的所有版本
pnpm view <包名> versions

# 如果镜像源没有某个版本, 给 scoped 包单独配源

ERR_PNPM_NO_OFFLINE_META

离线模式下缓存里没有元数据。 解决: 先联网装一次, 之后才能离线。

pnpm 配置镜像源

1
2
3

pnpm config set registry https://registry.npmmirror.com
pnpm config set fetch-retries 3
pnpm config set fetch-timeout 120000

项目级写在 package.json 或 .npmrc:

1
2
3

registry=https://registry.npmmirror.com/
fetch-retries=3
fetch-timeout=120000

scoped 包要单独配

这是镜像源最常见的坑: 私有或小众的 scoped 包, 镜像源可能没有同步。

1
2

registry=https://registry.npmmirror.com/
@yourorg:registry=https://registry.npmjs.org/

含义: @yourorg/ 开头的包走官方源, 其他走镜像。

pnpm vs npm 的选择

pnpm 有一个显著优势: 硬链接机制, 相同版本的包在磁盘上只存一份。

实测对比(同一项目): npm 的 node_modules 通常 300-500MB, pnpm 可能只有 100-200MB, 安装速度也更快。

但注意: pnpm 用的是 node_modules/.pnpm/ 结构, 有些工具(尤其是老项目)不兼容, 遇到奇怪的模块找不到问题, 可以先用 npm 验证。

六、Docker 场景的同类问题

Docker 拉镜像慢或失败, 根因和 npm 高度相似。

镜像拉取失败

pull access denied

排查顺序:

1
2
3
4
5
6
7
8
9
10
11

# 1. 确认镜像名和标签存在
docker search <镜像名>
docker manifest inspect <镜像名>:<标签>

# 2. 确认没超出Docker Hub 匿名拉取限额
# 匿名用户: 100 次/6 小时(按 IP 算)
# 登录免费账号: 200 次/6 小时
docker login

# 3. 确认网络能通
docker pull hello-world

配置国内镜像加速器

Docker Desktop: Settings → Docker Engine, 加:

1
2
3
4
5
6

{
  "registry-mirrors": [
    "https://docker.m.daocloud.io",
    "https://dockerproxy.com"
  ]
}

Linux 上配在 /etc/docker/daemon.json, 然后 systemctl restart docker。

改完一定要重启 Docker Desktop 才生效, 这是最常见的”我配了但没用”。

验证加速器是否生效

1

docker info | grep -A3 "Registry Mirrors"

有输出说明配置生效; 空的话说明没生效。

七、证书相关问题

CERT_HAS_EXPIRED 或 UNABLE_TO_VERIFY_LEAF_SIGNATURE。

正确做法(按优先级)

1. 更新根证书(推荐)

老版本的 Windows 或 Node 可能没有新的根证书。

1

npm install -g nss-updates  # 或在系统层面更新证书

或直接更新 Node.js 到 LTS 版本。

2. 换源

如果是特定镜像的证书问题, 换个源可能就绕过了。

3. 临时禁用 SSL 校验(不推荐, 但有时是唯一办法)

1

npm config set strict-ssl false

但要知道代价:

strict-ssl=false 会让npm 不再验证 HTTPS 证书, 这意味着你无法确认下载的包是否被中间人篡改。 在公共 WiFi、公司网络或有代理的环境下, 这是实打实的供应链安全风险。

我的建议是把它当作最后的手段, 且只在临时使用, 解决后立刻改回true。

npm config set strict-ssl true 改回来。

顺带说一句: 很多老教程会让你直接关SSL, 这在当年网络环境复杂时有其道理, 但现在镜像源的证书普遍是正常的, 关SSL 的弊大于利。

八、权限问题

Linux/macOS 下 EACCES 或 EPERM:

不要用 sudo npm install —— 这会让文件属主变成 root, 后面更麻烦。

正确做法:

1
2
3
4
5
6

# 改 Node 的全局安装目录
sudo mkdir -p /usr/local/lib/node_modules
sudo chown -R $(whoami) /usr/local/lib/node_modules

# 然后正常安装
npm install -g <包名>

或者用 nvm 管理 Node, 从根本上避免权限问题。

九、一个通用的排查流程

把上面的内容浓缩成一张流程图:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 第 0 步: 确认症状类型
npm install2>&1 | tee install.log
grep -oE "ETIMEDOUT|ECONNRESET|ENOTFOUND|CERT_HAS_EXPIRED|EACCES|ERR_PNPM_[A-Z_]+" install.log

# 第 1 步: 确认源可达(最常见原因)
npm config get registry
curl -s -o /dev/null -w "%{http_code}\n" -m 15 $(npm config get registry)react

# 第 2 步: 确认无代理干扰
echo $HTTP_PROXY; npm config get proxy

# 第 3 步: 最小化验证
npm view react version

# 第 4 步: 清理缓存重试
npm cache clean --force
npm install

# 第 5 步: 换源重试
npm config set registry https://registry.npmmirror.com/
npm install

按顺序走, 不要跳步。 大多数情况在第 1 或第 5 步就解决了。

十、小结

最核心的三条:

1. 先诊断再动手。 npm config get registry + npm view react version 这两条命令能定位八成问题。

2. 换源优先于调参数。 源不可达的时候, 把超时调到 10 分钟只是让你多等。

3. 别随手关 SSL。 那是用安全换 convenience, 记得到手改回来。

一个长期建议: 在项目里放一个 .npmrc(而不是只在全局配), 这样新人 clone 下来就能用, 也不会因为某台机器配置过期而卡住。

最后一个实用技巧: 遇到 npm 问题时, 先试试 pnpm install。 有时候不是 npm 坏了, 而是 npm 和这个项目的依赖树合不来。

参考:

• npm 官方文档配置项: https://docs.npmjs.com/configuring-npm
• npmmirror 源: https://npmmirror.com
• pnpm 配置: https://pnpm.io/config

前言

大部分技术博客都装了统计代码, 但装了之后呢?

我见过太多站点的状态是: 代码挂着, 后台注册了, 然后再也没打开过。 偶尔想起来看一眼, 发现数据零零散散, 看不出所以然, 最后还是不知道该写什么、该优化什么。

统计工具的价值不在于”有一个数字”, 而在于”能回答具体问题”。 这篇讲怎么把工具用起来。

一、先想清楚: 你想回答什么问题

装统计之前, 先问自己三个问题:

关键结论先说:

• 百度统计: 唯一能拿到搜索关键词的免费工具。对中文技术博客来说, 这是最重要的功能—— 能直接告诉你读者在搜什么, 从而告诉你下一篇该写什么。
• GA4: 地区分布更准, 且对国内站的数据也能记录(但常被拦截), 适合有海外流量或想看地区差异的。

怎么选: 按你的实际情况挑

两个工具各有不可替代的部分, 选哪个取决于你的站点情况:

只需要百度统计就够的情况:

• 站是中文技术博客, 流量主要来自百度搜索
• 你的核心需求是搜索词报告(指导选题)
• 不想维护两套后台

建议两个都装的情况:

• 你有海外读者(收到过英文评论, 或后台出现境外来源)
• 需要区分不同国家和地区的访问质量(比如想知道欧美读者占比)
• 你已经在用 Google 生态的其他工具(Search Console 等), 顺手一起配

折中做法: 先只装百度统计, 等到确实需要地区分布数据时再加 GA4。 两个工具互不冲突, 随时可以加。

常见情况是: 国内技术站先装百度统计跑一段时间, 等有海外流量了再补 GA4。

二、百度统计配置(能拿到搜索词)

为什么百度统计值得优先了解

百度搜索是国内流量的大头, 而百度统计能看到用户在搜索框里实际输入了什么词才点到你的文章。

这个数据没有任何其他工具能提供。 Google Analytics 在国内基本收不到数据, 也拿不到百度搜索词。

Hexo + Butterfly 怎么配

第一步: 在百度统计后台添加站点

拿到一个 hm.baidu.com/hm.js?xxxxxxxx 形式的代码。

第二步: 填进 Butterfly 配置

_config.butterfly.yml 里已经有这一项, 把 ID 换成你自己的:

1

baidu_analytics: 你的统计ID

拿到 ID 的方法: 在百度统计后台点”管理” → “获取代码”, 会看到类似 hm.baidu.com/hm.js?xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx 这样一串, 取问号后面那串 32 位字符, 填到配置里。

注意这里只填 ID, 不填完整脚本 URL—— Butterfly 已经内置了 hm.baidu.com/hm.js 的引用逻辑, 填完整 URL 会导致脚本加载两次。

常见错误: 把 https://hm.baidu.com/hm.js?xxx 整段粘进去。 主题会自己拼 hm.baidu.com/hm.js? + 你填的内容, 结果变成 hm.baidu.com/hm.js?https://hm.baidu.com/hm.js?xxx, 统计失效。

验证是否装成功

三个检查点:

1. 看页面源码

1

# 打开任意文章页, 查看源代码, 搜 hm.baidu.com

应该能看到类似:

1
2
3
4
5
6
7
8

<script>
var _hmt = _hmt || [];
(function() {
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?你的统计ID";
  ...
})();
</script>

2. 实时统计页

百度统计后台有”实时访客”页面。 打开自己的博客页面, 实时页面应该能看到自己。

如果看不到自己, 说明代码没生效或被拦截。

3. 隔天看数据

新站前24 小时数据不准(需要积累), 但第二天应该有数据进来。

百度统计的隐私合规提醒

在接入 GDPR 区域合规要求后, 百度统计提供符合欧盟标准的版本。 但前提是你得有隐私政策页面, 并在页面上做 Cookie 提示。

关于合规要求, 参见本站的隐私政策一文。

三、GA4 配置(地区分布更准)

GA4 相比百度统计的优势

结论: 中文技术站用百度统计看搜索词, 用 GA4 看地区分布。 两个互补。

配置方法

第一步: 创建 GA4 媒体资源

在 https://analytics.google.com 里创建, 拿到 G-XXXXXXXXXX 格式的 ID。

第二步: 填进配置

_config.butterfly.yml:

1

google_analytics: G-XXXXXXXXXX

同样注意: 只填 ID,不要填完整脚本地址。

第三步(可选): 站点验证

GA4 后台要求验证网站所有权, 最简单的方式是在 source/ 下建一个文件:

1
2

mkdir -p source/gtag
echo "google-site-verification-xxxxxxxxxxxx.html" > source/gtag/google-site-verification-xxxxxxxxxxxx.html

构建后访问 https://你的域名/gtag/google-site-verification-xxxxxxxxxxxx.html 即可。

GA4 里值得看的报告

1. 国家/地区分布(Reports > Geography)

这是 GA4 最不可替代的能力。 如果发现某个国家/地区占比异常高, 说明你的内容在那里有意外受众。

2. 流量来源(Reports > Traffic acquisition)

按 Source/Medium 分组, 能看出:

3. 内容页表现(Reports > Content)

按页面浏览次数排序, 看你哪篇文章最受欢迎。

4. 自定义事件(Reports > Engagement > Events)**

如果你在站点里加了”复制代码”、”点击广告”之类的自定义事件, 这里能看到。

四、拿到数据后: 判断下一篇写什么

这是统计工具真正的价值所在。

方法一: 百度搜索词报告(最重要)

路径: 百度统计 → 搜索分析 → 搜索词

这个报告会列出访客实际搜索的关键词, 按展现和点击排序。

典型的三种情况:

情况1: 搜索词命中但点击率低

比如某词展现 500, 点击 10(点击率 2%)。

说明: 你的文章有可能排到前列但标题不吸引人。
做法: 优化标题, 让它更贴近搜索词。

情况2: 某些高频搜索词你完全没有对应文章

比如某个词展现 300, 但你的站内搜索里没有相关文章。

说明: 这就是下一篇该写的。 有真实需求, 搜不到就等于没接住。

情况3: 词很精准但展现极低

说明这个词搜索量本身小, 但转化率可能很高(目标读者更明确)。
判断: 如果这个词和你的核心主题高度相关, 值得写小而精的深度文。

方法二: 内容页表现找”潜力文章”

在百度统计或 GA4 里按浏览量排序, 找出:

浏览量高但跳出率也高 → 内容可能不够深或有误导, 值得补充完善

浏览量低但停留时间长 → 好内容但标题不吸引人, 可以换个更吸引人的写法重发或改标题

有浏览但几乎没有评论/互动 → 缺互动引导, 可以考虑在文末加提问

方法三: 搜索词 + 站点内容做差集

这个方法最能指导选题。

1. 去百度统计导出搜索词报告(CSV)
2. 列出所有关键词
3. 对每个词, 在自己博客里搜一下有没有相关文章
4. 没找到对应文章的词, 就是选题候选

我做这件事的体会是: 导出一次 CSV, 顶你盯一个月后台。 因为后台的数据是分散的, 而导出的列表能让你一眼看出缺口在哪。

五、几个实用技巧

1. 给不同页面加来源标记

想知道某个具体推广渠道的效果(比如你在某平台发了链接), 可以用 URL 参数区分:

1
2

<!-- 在外链上加参数 -->
<a href="https://你的域名/xxx.html?utm_source=weibo&utm_medium=social">

主流统计工具会自动识别 utm_* 参数, 在来源报告里单独列出来。

2. 统计代码放哪

Butterfly 已经帮你放好了(<head> 里)。 不要自己再手动注入一份——重复加载会让 PV 统计翻倍。

判断方法: 在页面源码里搜 hm.baidu.com, 如果出现两次, 就是重复了。

3. 不要看单日数据

新站或低流量站的单日数据没有统计意义, 波动比信号大得多。

建议看:

• 周报: 比日报稳定
• 月报: 看趋势和季节性
• 同比: 和去年同期比

4. PV / UV 比例是个有意思的指标

• PV/UV < 2: 读者来了就走, 内容可能不够深或者不够对症
• PV/UV 2-4: 比较健康, 说明有回访
• PV/UV > 4: 内容很实用, 或者站点结构让读者容易”逛”

5. 认识”直接访问”

direct / (none) 这一项高, 不一定是好事。

如果很高而搜索流量很低, 说明读者基本是靠收藏或手动输入来的——说明你的站没什么自然流量, SEO 没起效, 或者内容传播主要靠熟人。

这种情况下加大 SEO 和内容推广的投入, 比继续写同类文章更值得。

六、常见问题

装了统计但没有数据

排查清单:

1. 源码里有脚本吗? → 没有就是配置没生效
2. 有脚本但后台没数据? → 检查是否被浏览器广告拦截器屏蔽(测试用无痕模式关掉插件)
3. 数据隔天才出来? → 正常, 实时页面能看自己
4. GA4 没数据? → 国内访问 Google Analytics 常被拦截, 这是预期行为; 百度统计不受影响

两个统计工具的数据对不上

正常。 它们的口径不同(去重规则、时区、过滤规则), 有 10-20% 的差异不用管。

看趋势就好, 不要纠结绝对值的精确。

统计代码会不会影响性能

基本不会。 统计脚本都是异步加载的, 不阻塞页面渲染。

但如果你加载了很多第三方脚本(广告、多个统计、字体 CDN), 累积起来会影响首屏时间。 这时候该考虑合并或用异步/延迟加载。

七、小结

最小可用组合:

1. 百度统计 —— 拿搜索词, 指导选题
2. GA4 —— 看地区分布和流量来源(需要时再加)
3. 每月导出一次搜索词报告, 和站点内容做差集

核心观念: 统计工具是用来指导行动的, 不是用来看好看的。

UV 从 3 涨到 30 不值得高兴; 但”发现有个高频搜索词没对应文章,赶紧写了” 这件事, 价值远大于前者。

参考:

• 百度统计: https://tongji.baidu.com
• Google Analytics 4: https://analytics.google.com
• GA4 文档: https://support.google.com/analytics/

前言

做个人博客有件事很微妙: 前期完全没人管, 一旦想接广告变现, 合规就成了硬门槛。

我见过不少技术博主卡在这一步—— AdSense 审核反复被拒, 百度联盟一直 pending, 最后才发现缺的不是内容, 就是一个像样的隐私政策页面, 和页脚那行不起眼的备案号。

这篇把这件事一次讲清楚。只讲个人博客用得上的部分, 公司主体、法务合规这些不在范围内。

一、先搞明白: 到底谁在要求什么

不同平台的规则差异很大, 搞混了会白折腾。

有个关键区别: 备案是行政要求(给监管看的), 隐私政策是平台要求(给用户看的)。

前者没做是违法, 后者没做是过不了审核。

二、ICP 备案与公安备案

备案放在哪: 页脚最显眼处

国内备案要求在网站底部显著位置展示备案号, 并且链接到备案系统。

Hexo + Butterfly 里, 页脚自定义文本在 _config.butterfly.yml:

1
2
3
4
5
6

footer:
  custom_text: >
    <a href="https://beian.miit.gov.cn" target="_blank">你的省份ICP备xxxxxxxx号-1</a>
  icon:
    height: 32
    width: 32

点进去是加密串, 之后就是公安备案:

1
2
3
4
5
6
7
8
9

footer:
  custom_text: >
    <a href="https://beian.miit.gov.cn" target="_blank">你的省份ICP备xxxxxxxx号-1</a><br>
    <a target="_blank" href="http://www.beian.gov.cn/portal/registerSystemInfo?recordcode=xxxxxxxx">
      <img src="/img/beian.png">你的省份公网安备 xxxxxxxxxxxx号
    </a>
  icon:
    height: 32
    width: 32

公安备案的图标别乱改

公安备案要求同时展示图标, 而且图标不能变形、不能改颜色。常见做法是直接放一张图片。

别为了美观自己重绘这个图标, 官方有明确要求, 被检查出来会扣分。

备案号变更后要同步

域名备案信息变更(比如换服务器、主体变更), 要在 30 日内更新备案系统, 同时同步改页脚, 两边不一致会被判为”信息不实”。

三、隐私政策页面: 为什么要建, 怎么建

为什么必须要有

两个层面:

法律层面: 依据《个人信息保护法》, 处理用户个人信息(包括收集访问日志、Cookie)需要有合法基础, 并告知用户。境外平台(AdSense)更严格, 明确要求站点提供隐私政策页。

平台层面: AdSense 的审核清单里, 隐私政策是硬性项。缺了会直接被拒, 而且理由往往写得很模糊, 让你猜半天。

Hexo 里怎么建页面

第一步: 建文件

在 source/ 下建一个目录, 放 index.md:

1

mkdir source/privacy

source/privacy/index.md:

1
2
3
4
5

---
title: 隐私政策
date: 2026-10-21
type: privacy
---

注意 permalink 要匹配目录名, 这样访问 /privacy/ 就是这个页面。

第二步: 加到菜单

_config.butterfly.yml:

1
2

menu:
  隐私政策: /privacy/ || fas fa-shield-halved

第三步: 写内容

模板见下一节, 按实际情况改。

隐私政策要写哪些内容

按主流平台的模板, 必须覆盖这几块:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54

---
title: 隐私政策
date: 2026-10-21
type: privacy
---

# 隐私政策

最后更新: 2026-10-21

本站(你的域名)是一个技术分享性质的静态博客。 这篇政策说明本站会收集哪些信息、为什么收集, 以及你有哪些权利。

## 收集的信息

### 访问日志
托管服务商(你的 CDN 或服务器厂商)在处理请求时会生成访问日志, 可能包含: IP 地址、请求时间、请求的页面、浏览器标识、来源地址。 这些日志**仅用于故障排查和统计, 不会用于识别你个人身份**。

### Cookie 与本地存储
本站使用以下第三方服务, 它们可能在你浏览器中设置 Cookie 或使用本地存储:

| 服务 | 用途 | 说明 |
| :-- | :-- | :-- |
| 百度统计 | 访问量统计 | 境内服务, 数据在境内 |
| Google AdSense | 广告投放 | 境外服务, 涉及跨境传输 |
| Valine 评论系统 | 评论功能 | 评论内容会公开显示 |

> 这张表是**举例**, 请按自己站点实际接入的服务增删。 原则是: 页面上加载了哪个第三方服务, 政策里就要提到哪个。 用不到的删掉, 漏掉的补上。

### 评论
如果你发表评论, 评论内容、昵称和邮箱会存储在第三方服务器(LeanCloud)并公开展示。 **请不要在评论中填写敏感个人信息。**

### RSS 订阅
本站的RSS 订阅源不收集个人信息, 但你使用的阅读器可能有自己的数据策略, 那部分由阅读器提供方负责。

## 数据的用途与保存

收集的信息仅用于: 站点运行与故障排查、访问量统计、广告投放优化。 不用于出售、不用于非法目的。

## 第三方服务与跨境传输

部分第三方服务(如 Google AdSense)的数据处理可能涉及境外。 使用本站即表示你接受该服务的数据处理方式。

## 你的权利

你可以随时:
- 请求删除与你的 IP 关联的访问数据(在合理范围内)
- 拒绝非必要 Cookie(通过浏览器设置)
- 撤回评论授权, 联系我删除你的评论

联系邮箱见本站联系方式页面。

## 政策更新

本政策可能随站点功能变化而更新, 重大变更会在本站公告。 继续使用本站视为接受更新后的政策。

关于隐私政策的几个常见误区

1. 不要写”我们不收集任何信息”

只要接了统计和广告, 就一定有 IP 和 Cookie 被处理。 写了反而显得不真诚, 平台审核人工看得出矛盾。

2. 必须有联系方式

Google 要求隐私政策里有可用的联系方式。 没有的话审核可能被拒。

3. 放在可达的位置

不能藏在页脚小字里让人找不到。 一般做法是页脚留链接, 或菜单里直接有。 我自己的站点是放菜单。

4. 声明要具体

“我们可能使用第三方服务”这种太空泛的表述没有意义。 要具体到服务名称和用途, 读者才能知道你拒绝了什么。

四、Cookie 与第三方脚本的披露

这是最容易被忽略的一块。 有些站点在隐私政策里写了, 但页面里实际加载的东西和声明对不上—— 这属于不实陈述, 审核和合规检查都过不去。

自查方法: 打开浏览器开发者工具的 Network 面板, 加载一个页面, 把所有第三方域名列出来, 逐个核对隐私政策里有没有提到。

常见的第三方请求:

如果用的是自建图床和 CDN(比如又拍云), 也要写进去, 别以为”自己的域名就不算第三方”。

五、评论区合规

评论功能也是个人信息处理的场景。

Valine 的特别之处

如果你用 Valine 评论, 要注意两点:

第一, 评论默认公开且会被搜索引擎收录。 这意味着评论里的邮箱等信息可能长期可检索。 引导用户不要在评论里留敏感信息。

第二, Valine 的后台管理需要绑定邮箱。 这个邮箱是管理员的, 不会展示在前台, 但要知道它在哪里。

加评论前的考虑

很多技术博客会选择只留评论但关闭邮件通知, 减少个人信息处理环节。

六、上线前自查清单

逐条确认:

• 页脚有 ICP 备案号, 点击跳转到工信部系统
• 公安备案号和图标已展示
• 有可达的隐私政策页面
• 隐私政策里有具体的第三方服务列表(不是泛泛而谈)
• 隐私政策里有联系方式
• 隐私政策最后更新日期是真实的
• 用浏览器 Network 面板核对过第三方请求, 与政策描述一致
• 评论框附近有”请勿填写敏感信息”的提示
• 备案信息与实际主体一致, 没有过期

七小结

优先级排序:

1. 隐私政策页面(最紧急, 影响变现审核)
2. 页脚备案展示(合规基础, 检查时会看)
3. 第三方服务具体披露(避免不实陈述)
4. 评论区的个人信息提示(有评论功能才需要)

这些工作加起来大概一两个小时, 但换来的是审核能过、不会被检查出问题。

我的体会: 很多技术人觉得合规是”务虚”, 尤其内容免费分享、不图赚钱的时候。 但一旦想让它长期稳定运行, 流量和收入都依赖平台信任, 合规就是那个最低成本的信任基础。

参考:

• 工信部 ICP/IP 地址/域名信息备案管理系统: https://beian.miit.gov.cn
• 公安互联网站备案: https://www.beian.gov.cn
• Google AdSense 政策与条款: https://support.google.com/adsense/
• 个人信息保护法(中国): http://www.npc.gov.cn/

前言

域名每年要钱, 服务器(如果是静态托管)也要钱, 有人会问: 个人博客靠什么覆盖成本?

常见的路径有三条:

1. 流量主 —— 最常见, 靠展示广告
2. 联盟推广 —— 靠推广产品拿佣金
3. 知识付费/赞助 —— 靠内容本身

这篇先写最实际的: 展示广告怎么接。同时也会说清楚收益的现实预期 —— 不吹数字,免得你按错误的期望去规划。

先算一笔账

假设你的硬成本是:

• 域名: 95 元/年
• 服务器/CDN: 静态托管可以是 0, 用云服务器约 100-300 元/年
• 合计约 200-400 元/年, 折合 每天 0.5-1.1 元

那么问题变成: 需要多少流量才能覆盖?

AdSense 的收益量级

AdSense 的收益和 CPM(每千次展示收益) 直接相关, 而 CPM 差异极大:

再叠加一个关键指标: RPM(每千次页面浏览的实际收益), 因为不是每个访客都会看到广告(要看展示率和点击率)。

RPM 通常只有 CPM 的 1/5 到 1/10。 举例,CPM 假设 20 美元, RPM 大概 2-4 美元。

需要多少流量

按国内流量、RPM 约 0.3 美元(约 2 元人民币)算:

结论很清楚: 靠 AdSense 覆盖成本, 需要日均几百到一两千 PV。 这不是个小数目。

如果你的站点是国内技术博客, 走百度联盟(百度的 RPM 对国内流量给得相对合理)会比 AdSense 稍好一些, 但量级是一样的。

顺便一提: 我自己的站点还挂了又拍云的联盟推广链接(CDN 和云存储), 这种”顺带推荐”的转化率不高, 但成本是零, 可以作为补充。

AdSense 接入流程

第一步: 申请账号

地址: https://www.google.com/adsense/

需要准备:

• 站点必须已经上线, 域名可访问
• 站点内容要够, 一般要求 20-30 篇有实质内容的文章
• 一个 Google 账号
• 收款信息(国内常见是招商银行/中国银行的双币账户, 或电汇)

第二步: 验证域名

在 AdSense 后台添加站点, 填写:

• 网站地址: https://zsyyblog.com
• 流量来源: 填”您在博客中撰写的内容”这类

然后它会给你一段验证代码, 放到网站 <head> 里。

Hexo 里怎么放? 两种方式, 选一种就行:

方式一(推荐): 用 Butterfly 内置的 google_adsense 配置

Butterfly 主题本身就预留了 AdSense 的加载位置(layout/includes/head/google_adsense.pug), 直接在 _config.butterfly.yml 里填发布商 ID 即可, 不用手写代码:

1
2
3

google_adsense:
  enable: true
  client: ca-pub-你的发布商ID

主题会自动把脚本注入到 <head>。

方式二: 手动用 inject 注入

如果不想用内置配置(比如想同时接多个广告平台), 自己注入:

1
2
3
4

inject:
  head:
    - |
      <script async src="https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js?client=ca-pub-你的发布商ID" crossorigin="anonymous"></script>

不要两个方式同时用, 脚本会被加载两次, 导致广告重复展示或报错。

第三步: 配广告位

验证通过后, 后台会生成多个广告位(代码形如):

1
2
3
4
5
6
7

<ins class="adsbygoogle"
     style="display:block"
     data-ad-client="ca-pub-XXXXXXXXXXXXXXXX"
     data-ad-slot="YYYYYYYYYY"
     data-ad-format="auto"
     data-full-width-responsive="true"></ins>
<script>(adsbygoogle = window.adsbygoogle || []).push({});</script>

关键点:

• data-ad-client —— 你的发布商 ID
• data-ad-slot —— 广告位 ID(在后台创建广告单元时拿到)
• data-ad-format="auto" —— 自适应尺寸, 强烈建议保留
• data-full-width-responsive="true" —— 移动端适配

每创建一个广告单元, 就有一个新的 slot ID。 可以在同一个网站下建多个(比如”文章底部”、”侧边栏”、”首页顶部”), 分别配置不同内容。

第四步: 放到文章里

Butterfly 把广告分成两块配置, 别搞混。

4.1 全局开关: google_adsense

这块负责加载 AdSense 的 JS 脚本, 在 _config.butterfly.yml:

1
2
3
4
5
6

google_adsense:
  enable: true
  auto_ads: true
  js: https://pagead2.googlesyndication.com/pagead/js/adsbygoogle.js
  client: ca-pub-你的发布商ID
  enable_page_level_ads: true

字段说明:

auto_ads: true 是最省事的方式。 Google 的自动广告会自己挑位置, 新手直接用这个, 不用手动插代码。

但自动广告的样式不可控, 有时位置很怪。想精细控制就关掉它, 用下面的手动广告位。

4.2 手动广告位: ad

这块是你自己贴的广告代码, 主题会把它插到指定位置:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

ad:
  index: |          # 首页, 每三篇文章插一次
    <ins class="adsbygoogle"
         style="display:block"
         data-ad-client="ca-pub-你的ID"
         data-ad-slot="你的广告位ID"
         data-ad-format="auto"
         data-full-width-responsive="true"></ins>
    <script>(adsbygoogle = window.adsbygoogle || []).push({});</script>

  aside: |          # 侧边栏
    <ins class="adsbygoogle"
         style="display:block"
         data-ad-client="ca-pub-你的ID"
         data-ad-slot="你的侧边栏广告位ID"
         data-ad-format="auto"
         data-full-width-responsive="true"></ins>
    <script>(adsbygoogle = window.adsbygoogle || []).push({});</script>

  post: |           # 文章页, 上一篇/下一篇之前
    <ins class="adsbygoogle"
         style="display:block"
         data-ad-client="ca-pub-你的ID"
         data-ad-slot="你的文章页广告位ID"
         data-ad-format="auto"
         data-full-width-responsive="true"></ins>
    <script>(adsbygoogle = window.adsbygoogle || []).push({});</script>

注意这三个位置的准确含义(看主题模板源码最准):

不确定的话直接翻模板看:

1
2
3
4
5

# 文章页广告插在哪
grep -B3 -A5 "ad.post" themes/butterfly/layout/post.pug

# 首页广告插在哪
grep -B3 -A5 "ad.index" themes/butterfly/layout/includes/mixins/indexPostUI.pug

踩坑提醒: ad 段下面的三个字段默认都是空的, 必须整段贴 HTML 才会生效。填了 enable: true 之类的主题并不支持, 贴上去会被当成广告 HTML 直接输出到页面上。

第五步: 手动插入自定义广告位

内置的三个位置不够用时(比如想放文章末尾), 用 inject 自己插:

1
2
3
4
5
6
7
8
9
10
11
12

inject:
  bottom:
    - |
      <div style="margin:20px 0;">
        <ins class="adsbygoogle"
             style="display:block"
             data-ad-client="ca-pub-你的ID"
             data-ad-slot="你的广告位ID"
             data-ad-format="auto"
             data-full-width-responsive="true"></ins>
        <script>(adsbygoogle = window.adsbygoogle || []).push({});</script>
      </div>

注意: inject 只有 head 和 bottom 两个键, **没有 post-bottom**。上面这段是全站生效的, 如果只想要文章页有广告, 还是在 post.pug 里加更精准。

另外 inject 的内容是纯字符串(源码里 data.join('')), 不能在里面写模板变量。上面这段广告代码的 ID 是固定的, 所以没问题; 但如果你想动态取当前文章的 ID, 就得改主题模板。

广告放在哪里最合适

这不是随便放的, 位置直接决定点击率。

推荐位置

一个重要原则

Google 对”误点”非常敏感。 如果广告做得像网站原生按钮, 用户以为是点别的东西, 点错了 —— 这算”无效点击”。

后果: AdSense 会警告, 严重时直接封号, 严重的会封整个 AdSense 账号(所有站点一起完)。

所以:

• 广告要有明确的”广告”标识
• 不要做”继续阅读”这种伪装成功能按钮的样式
• 不要用会自动跳转的浮层广告
• 不要自己点自己的广告

百度联盟接入

与 AdSense 的差异

已备案的国内站点, 百度联盟往往比 AdSense 更实际。

配置流程

1. 访问 https://union.baidu.com/ 注册
2. 提交网站信息 + 备案号
3. 等待审核(通常 1-3 天)
4. 审核通过后创建广告位, 拿到推广位 ID
5. 在页面里放推广代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

<div id="BAIDU_ADC_xxx" class="baidu_ad"></div>
<script>
var _HMT = _HMT || [];
(function(){
  var hm = document.createElement("script");
  hm.src = "https://hm.baidu.com/hm.js?你的百度统计代码";
  var s = document.getElementsByTagName("script")[0];
  s.parentNode.insertBefore(hm, s);
})();
</script>
<script>
(function(){
  var i = document.createElement("script");
  i.src = "https://cpro.baidu.com/cpro/ui.js?siteid=你的站点ID&callback=__cpro__&use=3600&referer=http://你的域名/";
  ...
})();
</script>

具体的推广代码从百度联盟后台直接复制, 不用手写。

被封号的几个雷区

这个话题值得单独说, 因为很多新手是”莫名其妙”被封的。

1. 点击率异常高

CTR(点击率)如果长期超过 10% 左右, 会被判定为无效点击。正常文章博客的 CTR 通常在 1-5%。

2. 误点设计

前面说过,这是最常见的原因。

3. 内容不足以申请

刚建站、没几篇文章就挂广告, 审核可能不通过; 或者通过后没有真实流量, 收益太低, 账号反而处于”低质”状态。

4. 流量来源不健康

买来的垃圾流量是最大的雷。 短期能刷出可观收益, 但被检测到后基本是永久封禁, 账号里的所有站点一起没。

5. 广告和内容不匹配

技术博客里放游戏广告、或者放高利贷类广告, 会被判定为”低质量内容变现”, 影响账号信誉。

6. 用多个账号规避

被封后开新号继续挂, 系统会通过设备、IP、支付账户关联识别, 结果是全部封禁。这是最不划算的”聪明做法”。

提升收益的实际手段

广告收益的天花板不高, 想提高只能从这几个方向:

提高 PV 而不是 CTR

CTR 提升空间有限(而且提太高有风险), 但流量增长是线性收益。

具体做法: 提升搜索排名(SEO)、做 RSS 分发(见 518 篇)、在技术社区分享。

提高 RPM 而不只是 PV

RPM 取决于访问者所在地区和广告类型。欧美访客的 RPM 是国内访客的 5-10 倍。

如果你的内容是中文技术教程, 目标读者天然在国内。想接高价值广告, 可以考虑:

• 写英文版(用翻译工具 + 人工润色)
• 面向海外华人的内容

混合变现

只靠展示广告太单薄, 可以叠加:

对技术博客来说, 联盟推广其实比展示广告更划算 —— 因为它不打扰阅读, 成交佣金还比 RPM 高。接云服务、域名、主机这类推广, 和内容天然相关。

上线前的检查清单

准备提交审核前, 逐条确认:

• 站点能正常访问, HTTPS 有效
• 至少 20-30 篇有实质内容的文章
• 没有空分类、空标签页
• 移动端显示正常(现在大部分流量来自移动)
• 广告位置不会误触
• 隐私政策页面(欧美站点必备, AdSense 要求)
• 备案号展示(国内备案要求)

隐私政策页面可以用 Butterfly 自带的页面功能建一个, 简单说明用了哪些 Cookie 和第三方服务即可。

小结

1. 先想清楚收益预期 —— 覆盖域名费需要日均几百到一两千 PV, 别指望几百 IP 就能赚钱
2. AdSense 适合有海外流量或英文内容的站, 百度联盟适合已备案的国内站
3. 广告位置优先选文章末尾, 收益最好且不伤体验
4. 千万别碰”无效点击” —— 那是封号的主要原因, 而且会连累所有关联站点
5. 别买垃圾流量 —— 短期收益长期封号
6. 展示广告之外, 联盟推广对技术博客更划算

最后一条我的体会尤其深: 技术博客的用户信任度是最值钱的资产。 为了几十块钱的展示收益, 把用户体验做烂, 是很不划算的买卖。联盟推广、原创内容、良好的阅读体验, 这些才是能长期做下去的路子。

参考链接:

• Google AdSense 官方文档
• 百度联盟官网
• Google 违规政策 - 无效点击
• Butterfly 主题文档 - 广告配置

前言

之前写过三篇 Hexo SEO 系列(搜索引擎原理、站内优化、提升排名), 讲的多是 meta 标签、关键词、内外链这些。

但有一个东西漏了 —— 结构化数据。

它的作用是把”这是一篇文章, 作者是谁, 什么时候发的, 封面图是哪张”这类信息, 用机器能读的格式告诉搜索引擎。好处很直接: 搜索结果里可能直接显示出封面图、作者名、发布时间, 点击率比纯文字结果高。

这篇记录怎么接。

原理: 什么是 JSON-LD

三种格式, 选 JSON-LD

结构化数据有三种写法:

选 JSON-LD 的理由: 与 HTML 完全分离。 写在 HTML 属性里的方案, 改模板容易把结构化数据改坏; JSON-LD 是一段独立的代码, 不动页面结构, 维护成本最低。

长什么样

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "文章标题",
  "image": "https://example.com/cover.png",
  "datePublished": "2026-10-21T11:05:42+08:00",
  "dateModified": "2026-10-21T11:05:42+08:00",
  "author": {
    "@type": "Person",
    "name": "竹山一叶"
  },
  "publisher": {
    "@type": "Organization",
    "name": "竹山一叶的小家"
  }
}
</script>

搜索引擎会解析这段 JSON, 提取成知识图谱里的实体。

第一步: 加到 Butterfly 主题里

Butterfly 提供了 inject 机制, 可以往页面里塞代码。

先说清楚这个版本的 inject 支持哪些位置。 我查了本地主题源码, 实际只有两个注入点:

源码里就这两行:

1
2
3
4
5

// layout/includes/head.pug
!=fragment_cache('injectHead', function(){return injectHtml(theme.inject.head)})

// layout/includes/additional-js.pug
!=fragment_cache('injectBottom', function(){return injectHtml(theme.inject.bottom)})

这意味着没有”仅文章页”的注入点。 网上很多教程写的 inject.post / inject.post-bottom 在这个版本里不生效 —— 配了也不会被渲染。

那文章级的 JSON-LD 怎么加?

既然没有文章级注入点, 就用 head, 但在代码里自己判断当前是不是文章页。

1
2
3
4
5
6
7
8
9
10
11
12

inject:
  head:
    - |
      <% if (page.post) { %>
      <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "BlogPosting",
        ...
      }
      </script>
      <% } %>

page.post 在文章页上存在, 在独立页面、分类页、标签页上都是 undefined, 用它判断最直接。

注意 inject 的格式: 源码里是 data.join(''), 所以每一项必须是一个字符串, 不能写成 { code: 'xxx' } 这种对象结构。写成对象会渲染成 [object Object]。

顺带说明: Pug 模板里的条件语法

Butterfly 用 Pug, 但 inject 的内容是字符串, 会被当成普通文本输出, 不会被 Pug 编译。

所以上面的 <% if (page.post) { %> 这种 EJS 风格语法, 在 inject 里同样不会被解析 —— 它会原样输出到页面上。

正确做法是改用主题的标签系统, 或者接受所有页面都注入。

考虑到这一点, 更实用的方案是: 给所有页面都注入 JSON-LD, 但用不同的 @type 区分。搜索引擎能接受一个页面里有多个 JSON-LD 块, 它会按类型分别理解:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

inject:
  head:
    - |
      <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "WebSite",
        "name": "...",
        "url": "..."
      }
      </script>
    - |
      <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "BlogPosting",
        ...
      }
      </script>

如果你的站点没有独立页面(关于页等), 或者独立页面很少, 直接全站注入 BlogPosting 也没有大碍。 独立页面通常就那么几个, 搜索引擎不会因为一两个页面的类型标注不精确就惩罚整个站点。

另一个更稳的方案: 直接改主题模板。 主题的 layout/post.pug 是 Pug 文件, 里面可以用真正的 Pug/JS 语法判断页面类型。代价是主题升级时可能要重新改(所以要先改 themes/butterfly 还是用 extend/inject 覆盖, 取决于你愿不愿意接受维护成本)。

第二步: 动态取值

上面那段 JSON 里的字段不能写死 —— 每篇文章的标题、时间都不一样。得用模板变量动态填充。

先说个坑: inject 里不能用模板变量

这是最容易踩错的地方。 很多人以为 inject 里能写 <%- title %>, 实际上不行。

看主题源码里 inject 的实现:

1
2
3
4

// scripts/helpers/page.js
hexo.extend.helper.register('injectHtml', data => {
  return data ? data.join('') : ''
})

只是 join(''), 没有任何模板编译。 意味着你在 inject 里写的 <%- title %> 会原封不动地作为文本输出到 HTML 里, 页面上会出现字面量 <%- title %>。

结论: 需要动态取值的结构化数据, 不能靠 inject, 必须改主题模板。

正确做法: 在 post.pug 里加

Butterfly 的 layout/post.pug 是真正的 Pug 模板, 里面可以用完整语法。

在 layout/post.pug 的 block content 下面找合适位置(建议放在 article#article-container 之后), 加:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

if page.title
  script(type="application/ld+json").
    {
      "@context": "https://schema.org",
      "@type": "BlogPosting",
      "mainEntityOfPage": {
        "@type": "WebPage",
        "@id": "#{config.url}/#{page.path}"
      },
      "headline": "#{page.title}",
      "description": "#{page.description || page.excerpt || ''}",
      "image": "#{page.cover || config.site.img || config.site.logo}",
      "datePublished": "#{page.date.toISOString()}",
      "dateModified": "#{page.updated ? page.updated.toISOString() : page.date.toISOString()}",
      "author": {
        "@type": "Person",
        "name": "#{config.author}"
      },
      "publisher": {
        "@type": "Organization",
        "name": "#{config.title}",
        "logo": {
          "@type": "ImageObject",
          "url": "#{config.site.logo}"
        }
      },
      "keywords": "#{page.tags && page.tags.length ? page.tags.map(t => t.name).join(', ') : ''}"
    }

注意 Pug 里输出 JSON 用了 script(type="application/ld+json"). 这个写法 —— 末尾的点是 Pug 的”纯文本块”语法, 后面跟着的内容原样输出, 不做 HTML 转义。

这一点很关键: 如果用 script(type="application/ld+json")= #{json}, Pug 会把引号转义成 ", JSON 就废了。

几个关键点

标题字段用 headline 不是 name

文章类型用 headline。用 name 会被 Google 判为”不匹配预期类型”。

时间要用 ISO 8601 格式

page.date.toISOString() 输出的是 2026-10-21T03:05:42.000Z, 这是标准格式。

不要直接输出 page.date 本身, 默认的 2026-10-21 11:05:42 这种格式搜索引擎可能解析失败。

URL 要拼成绝对路径

#{config.url}/#{page.path} 拼出的是完整 URL, 搜索引擎最喜欢这种。

如果用 url_for(page.path), 得到的是带 config.root 的站内路径, 部署在根目录时也能用, 但部署在子目录时可能拼不完整。所以这里直接用 config.url 更稳。

封面图要有兜底

不是每篇文章都设了封面。所以要准备 fallback:

1

"image": "#{page.cover || config.site.img || config.site.logo}"

注意 page.cover 可能是相对路径(比如 /images/xxx.png)。搜索引擎对相对路径的 image 支持不稳定, 稳妥起见拼成绝对 URL:

1

"image": "#{page.cover && !page.cover.startsWith('http') ? config.url + page.cover : (page.cover || config.site.img || config.site.logo)}"

注意 cover 可能是相对路径, 而结构化数据的 image 最好是绝对 URL。如果搜索引擎抓不到完整 URL, 富媒体展示就不会生效。稳妥起见可以这样写:

1

"image": "<%- (cover && cover.startsWith('http')) ? cover : (config.root + (cover || config.site.img || config.site.logo)) %>"

第三步: 验证

写完不能靠猜, 必须用官方工具验。

Google 富媒体测试工具

地址: https://search.google.com/test/rich-results

输入你的文章 URL, 点测试。它会告诉你:

• 结构化数据是否被识别
• 哪些字段有警告或错误
• 预览效果长什么样

Schema Markup Validator

地址: https://validator.schema.org/

比 Google 那个更宽松, 主要用来检查 JSON 语法和 schema 定义是否符合规范。两个都跑一遍, 前者看实际效果, 后者查语法细节。

本地怎么验

本地还没部署的话, 可以直接看渲染后的 HTML:

1

hexo clean && hexo g

然后在 public/ 里找文章页面:

1
2

# 找到刚生成的文章
grep -l "application/ld+json" public/*.html | head -3

确认 JSON 语法没错:

1
2

# 提取 JSON 部分并校验格式
grep -A20 "application/ld+json" public/xxxxx.html | head -25

常见陷阱

陷阱一: JSON 里的引号没转义

这是最常见的错误。如果你的标题里带了英文双引号, JSON 就会解析失败, 整段结构化数据直接作废。

比如标题是 Hexo 配置的 "url" 该怎么填, 直接塞进 JSON 就崩了。

解决办法: 在模板里做 JSON 转义

Pug 的纯文本块(script(...).)不做 HTML 转义, 也就不会帮你转义 JSON 里的双引号。所以要在模板里手动处理。

在 post.pug 里定义一个变量先转义:

1
2
3
4
5
6
7
8

- var ldTitle = (page.title || '').replace(/\\/g, '\\\\').replace(/"/g, '\\"')
if page.title
  script(type="application/ld+json").
    {
      "@context": "https://schema.org",
      "@type": "BlogPosting",
      "headline": "#{ldTitle}"
    }

两个转义都要做: 先转义反斜杠 \, 再转义双引号 "。顺序反了会出问题 —— 先转义双引号的话, 新产生的 \ 会被二次处理。

description 和 keywords 同理, 有引号的话也要处理。

更省事的办法: front-matter 里的标题和描述尽量用中文标点(「」『』””), 避开英文双引号。但这只能规避, 不是根治。

陷阱二: 和主题自带的重复

Butterfly 5.x 本身没有内置 JSON-LD(我查过 layout/ 和 scripts/, 没有 ld+json 相关代码), 所以这块不会撞车。

但 canonical 和 og:url 这类标签, 主题和 SEO 插件只能有一个来源。

检查方法: 看渲染后的 HTML 里有没有多个同类标签。

1
2

grep -c "application/ld+json" public/xxxxx.html
grep -c "rel=\"canonical\"" public/xxxxx.html

大于 1 就要去掉多余的。

陷阱三: 忘了写 dateModified

datePublished 和 dateModified 都应该填。

• datePublished —— 文章首次发布时间
• dateModified —— 最后修改时间

老文章更新后, dateModified 是重要的信号。 只写 datePublished 会让搜索引擎以为这篇内容一直没变过, 不给重新抓取的权重。

你可以在 front-matter 里加 updated 字段:

1
2
3
4
5

---
title: 'xxx'
date: 2026-10-21 11:05:42
updated: 2026-10-25 15:30:00
---

陷阱四: 忘记改 updated 字段

上面那个 updated 不会自动更新, 得手动维护。

Hexo 有个插件可以自动根据 Git 提交时间生成, 但更简单的方式是每次改文章时顺手更新 updated 字段。

陷阱五: 结构化数据被当成作弊

不要在结构化数据里塞关键词。 比如把 keywords 写成 "Hexo,Hexo教程,Hexo博客,Hexo搭建,hexo主题", 这种堆砌反而会被判为垃圾信号。

keywords 字段就填真实的标签, 有几个填几个, 没有就干脆不填。

可以加的其他类型

BlogPosting 之外, 常见的还有:

加站点级 WebSite

WebSite 的字段所有页面都一样(站点名、站点 URL), 所以这条可以放心用 inject 注入 —— 不需要动态取值, 也没有引号转义问题。

1
2
3
4
5
6
7
8
9
10
11

inject:
  head:
    - |
      <script type="application/ld+json">
      {
        "@context": "https://schema.org",
        "@type": "WebSite",
        "name": "竹山一叶的小家",
        "url": "https://zsyyblog.com"
      }
      </script>

站点名和 URL 写死就行 —— 站点信息本来就不会每篇文章变。

不过要注意: 只有在页面真的有搜索功能时, 声明 SearchAction 才有意义, 否则 Google 会提示这个动作无效。

你如果开了 Butterfly 的搜索功能(search.enable: true), 可以加上:

1
2
3
4
5

"potentialAction": {
  "@type": "SearchAction",
  "target": "https://zsyyblog.com/search?q={search_term_string}",
  "query-input": "required name=search_term_string"
}

关于改主题模板的维护成本

前面说了要改 themes/butterfly/layout/post.pug。这会带来一个问题: 主题升级时这个改动会丢失。

两个应对办法:

办法一: 改之前留个备份

1
2

cd themes/butterfly/layout
cp post.pug post.pug.bak

升级主题后对比 diff, 把改动重新补回去。

办法二: 用 Hexo 的主题覆盖机制

Hexo 支持通过 _config.yml 里的 theme 字段配合 extend 生成器做覆盖, 但 Butterfly 官方文档对此支持有限。

更实用的第三种: 把 JSON-LD 的生成逻辑写成一个自定义 Hexo 过滤器或脚本, 输出到 source/ 下, 再用 inject 引入。这样升级主题不受影响。

不过说实话, 对大多数个人博客来说, 办法一就够用了 —— 一年升级主题一两次, 每次补一下也花不了几分钟。改之前记一下改了什么就行。

小结

接入结构化数据, 核心就三步:

1. 加代码 —— 文章级改 themes/butterfly/layout/post.pug, 站点级用 inject.head
2. 动态取值 —— Pug 里用 page.xxx, 时间转 ISO 8601, URL 拼绝对路径, 引号手动转义
3. 用官方工具验证 —— Google 富媒体测试 + Schema Markup Validator

最需要小心的三个点:

• inject 里不能用模板变量 —— 它只做 join(''), <%- title %> 会原样输出
• JSON 里的双引号要转义 —— 先转 \, 再转 ", 顺序不能反
• 别和主题自带的标签重复 —— canonical、og:url 这类一个来源就够了

结构化数据是纯增量的 —— 加错了顶多不起作用, 不会让搜索排名变差。所以值得花半小时配好它, 换来的是搜索结果里更丰富的展示。

参考链接:

• Google 富媒体搜索结果测试
• Schema Markup Validator
• Schema.org - BlogPosting
• Google 搜索中心 - 结构化数据通用指南

前言

写博客有个绕不开的问题: 读者怎么知道你有更新?

静态博客不像公众号那样有推送, 靠的是 RSS 订阅。但很多 Hexo 博客装好之后就没管过 RSS, 结果是:

• 搜索引擎抓不到新文章(虽然有 sitemap 兜底, 但覆盖率不如 RSS)
• 读者只能手动收藏首页
• 想订阅 RSS 的朋友发现没有 atom.xml, 直接放弃

这篇记录 Hexo 博客接入 RSS 的完整流程。

原理: RSS 是什么

先说清楚原理, 后面的操作就好理解了。

RSS 本质上就是一个 XML 文件, 里面按时间顺序列着你最新的文章:

1
2
3
4
5
6
7
8
9
10
11
12

<?xml version="1.0" encoding="utf-8"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>竹山一叶</title>
  <link>https://zsyyblog.com</link>
  <updated>2026-10-21T10:42:18.000Z</updated>
  <entry>
    <title>Hexo 博客添加 RSS 订阅</title>
    <link href="https://zsyyblog.com/196ff3fc.html"/>
    <updated>2026-10-21T10:42:18.000Z</updated>
    <content type="html">...</content>
  </entry>
</feed>

订阅者用阅读器(Feedly、Inoreader、RSSHub 等)定时拉取这个文件, 有新文章就推送。

关键点: RSS 文件是一个静态文件, 每次 hexo g 构建时自动重新生成。 不需要额外服务, 也不需要数据库。

第一步: 安装 feed 插件

Hexo 官方没有内置 RSS 支持, 需要装插件:

1

npm install hexo-generator-feed --save

装完会自动生成 atom.xml(和可选的 rss.xml)。

验证是否生效

1

hexo g

然后检查 public/ 目录:

1

ls public/*.xml

应该能看到 atom.xml 和 rss.xml。构建完不生成 XML, 就是插件没装上或者没启用。

本文写作时踩过一个坑: 习惯性写 hexo clean && hexo g, 结果 hexo clean 在 Windows 上卡了十几分钟没删完。原因是 hexo-fs 删目录时对所有文件发起无限并发的删除调用, 文件一多句柄就排队假死。文件多的话直接手动删更快:

1	rm -rf public db.json && hexo g

89 秒 vs 卡到没下文, 差别很大。

第二步: 配置输出

在 _config.yml 里加配置:

1
2
3
4
5
6
7
8
9
10
11
12

feed:
  enable: true
  type:
    - atom
    - rss2
  path:
    - atom.xml
    - rss.xml
  icon: https://img.zsyyblog.com/favicon.jpg
  limit: 20
  order_by: -date
  autodiscovery: true

各字段含义:

limit 别设太大。RSS 里塞几百篇全文, 拉取一次就好几 MB, 阅读器体验很差。20 篇左右最舒服。

⚠️ type 只认 atom 和 rss2 两个值。 写 rss 会被插件静默过滤掉 —— 不报错, 但 rss.xml 就是不生成。想同时输出两种格式, type 和 path 都得写成数组:

1
2
3
4
5
6
7
8
9

feed:
  enable: true
  type:
    - atom
    - rss2
  path:
    - atom.xml
    - rss.xml
  limit: 20

如果数组长度对不上(比如 type 写了两个但 path 只写一个), 插件会自动补齐, 但还是老实写全比较好。

关于 atom 还是 rss

简单说:

• Atom —— 格式更规范, 支持全文和摘要两种模式, 主流阅读器都支持
• RSS 2.0 —— 更老但更通用的格式, 兼容性好一些

建议两个都生成。Atom 给现代阅读器, RSS 2.0 兜住那些只认老格式的工具。两种格式指向同一批内容, 不会造成重复收录。

第三步: 在 Butterfly 中加订阅按钮

光生成 XML 还不够, 得让读者知道入口在哪。

Butterfly 自带的方案: 没有

先说个坑。Butterfly 5.x 主题里根本没有 RSS 按钮这个配置项 —— 不是默认关闭, 是主题源码里压根没有。你在 _config.butterfly.yml 里写:

1
2
3

rss:
  enable: true
  path: atom.xml

在 5.2.2 上是纯无效配置, 页面不会多出任何东西, 而且不会有任何报错提示你。网上很多教程（包括本文最初写的版本）都在讲这个 rss: 块, 但那是更早的版本或者别的分支。

验证方法很简单, 直接搜主题源码:

1

grep -rn "rss" themes/butterfly/layout/ themes/butterfly/scripts/

搜不到就是真没有。别浪费时间在配置上找。

零成本方案: 侧边栏社交图标

改主题模板之前, 先试试这个 —— Butterfly 的侧边栏头像下面有一排社交图标(GitHub、Email 那些), 那个位置固定在侧栏顶部, 每一页都在, 曝光比文章底部高得多。

它由 _config.butterfly.yml 的 social 配置驱动, 加一行就行, 不用碰任何主题文件:

1
2
3
4

social:
  fab fa-github: https://github.com/zsyyblog || Github
  fas fa-envelope: mailto:zsyyblog@qq.com || Email
  fas fa-rss: /atom.xml || RSS订阅

格式是 图标类名: 链接 || 悬停提示 || 颜色, 三个部分都可以省。

主题的渲染源码在 themes/butterfly/layout/includes/header/social.pug, 一共就 8 行:

1
2
3
4
5
6
7
8

each url, icon in theme.social
  -
    const [link, title, color] = url.split('||').map(i => trim(i))
    const href = url_for(link)
    const iconStyle = color ? `color: ${color.replace(/[\'\"]/g, '')};` : ''
    const iconTitle = title || ''
  a.social-icon(href=href target="_blank" title=iconTitle)
    i(class=icon style=iconStyle)

几个细节:

颜色那一段是可选的, 建议直接省略。侧边栏就那么几个图标, 一个是橙的另外两个是灰的反而显得跳。想跟整个站的主题色统一, 让它继承 --font-color 就行。

真要单独指定颜色, 引号必须保留 —— 少了会被 YAML 解析成别的类型, 颜色就静默丢了。

想同时给 RSS 2.0 留个入口? 再加一行指向 /rss.xml 就行, 两个图标并排。不过一般一个就够, 阅读器都认 Atom。

这个方案我认为是性价比最高的: 零代码改动、主题升级不受影响、全站每页都显示。改主题模板那种方案留给需要自定义样式的情况。

更醒目的订阅入口

文章底部再放一个按钮, 转化率会更高。先说清楚 inject 的位置限制。 Butterfly 5.x 的 inject 实际只有两个键:

没有 post-bottom 这样的文章级注入点。 网上教程里写的 inject.post-bottom 在这个版本不会被渲染。

所以想放在文章底部, 有两个办法:

办法一: 改主题模板(推荐)

在 themes/butterfly/layout/post.pug 里, 找到 include includes/post/post-copyright.pug 那一行(它在 .tag_share 之前), 在这两行之间插入:

1
2
3
4
5

//- RSS 订阅入口
.rss-subscribe
  a(href=url_for('/atom.xml') target="_blank" rel="noopener")
    i(class="fa-solid fa-rss")
    span= '订阅本站更新'

注意缩进是 4 个空格 —— 这段代码在 article#article-container 块内部, 顶格写会被 Pug 当成另一个块, 直接编译报错。

对应样式加到 source/css/ 下(比如 rss.css), 再在 _config.butterfly.yml 的 inject.head 里引一下:

1
2
3

inject:
  head:
    - <link rel="stylesheet" href="/css/rss.css">

source/css/ 下的文件会被原样拷贝到 public/css/, 所以这里用绝对路径 /css/rss.css 引用就行。

用 url_for('/atom.xml') 而不是写死 /atom.xml, 这样部署在子目录时也能正确指向。图标类名 fa-solid fa-rss 依赖主题加载的 Font Awesome(通过 asset.fontawesome 配置项), Butterfly 默认带 FA6, 直接能用。

办法二: 放首页

如果不想改主题, 可以用 inject.bottom 加一段 JS, 在文章页动态插入按钮:

1
2
3
4
5
6
7
8
9
10
11
12

inject:
  bottom:
    - |
      <script>
      (function () {
        var box = document.createElement('div');
        box.className = 'rss-subscribe';
        box.innerHTML = '<a href="/atom.xml" target="_blank" rel="noopener">📢 订阅本站更新</a>';
        var c = document.getElementById('post');
        if (c) c.appendChild(box);
      })();
      </script>

注意 pjax: 上面这段只在首次加载时执行, 切换页面后按钮会消失。需要额外监听:

1

document.addEventListener('pjax:complete', function () { /* 重新插入 */ });

所以还是办法一更省心。

这里的路径是站点根目录下的相对路径。如果你的博客部署在子目录, 需要改成 /子目录/atom.xml, 或者用 url_for() 自动处理。

第四步: 提交订阅源

生成好了就该让人订阅。以下平台的收录比较有效。

提交给阅读器服务

大部分平台的提交流程都是: 注册 → 填入你的 RSS 地址 → 验证。

提交给搜索引擎

RSS 对搜索引擎的价值在于加速收录。sitemap 告诉搜索引擎”这些页面存在”, RSS 则是”这些是新的”。

RSS 和主动推送是两种不同机制, 各有各的用处:

sitemap 是”定期汇报全站有哪些页面”, 主动推送是”新文章一发布就通知”。两者不冲突, 有条件的话两个都配。

如果你的站目前只配了 sitemap 生成(也就是只生成 baidusitemap.xml 而没有自动推送), 那 RSS 作为另一种”告诉搜索引擎新内容”的途径, 同样有补充价值。

校验 RSS 是否有效

可以用在线工具检查:

• https://validator.w3.org/feed/ —— W3C 官方校验器
• https://www.rssboard.org/rss-validator —— 检查是否被主流阅读器识别

校验报错别忽略。 常见问题是 XML 里有非法字符(比如文章里写了 & 但没转义), 这会导致某些阅读器整个源都读不出来。

常见问题

生成的是 atom.xml, 但别人要 rss.xml

前面说了, type 可以传数组同时输出两个。

订阅源里没有新文章

按顺序排查:

1. 重新构建, 确认 XML 里有新 entry
2. 检查 feed.limit 是不是太小(比如设成 1, 旧的被顶掉了)
3. 确认 public/atom.xml 确实更新了
4. 确认 CDN 缓存 —— 静态文件如果走了 CDN, 可能还在发旧版本

文章内容在订阅源里是乱码

先确认是真乱码还是显示问题。Atom 的规范格式要求 <?xml version="1.0" encoding="utf-8"?>, 插件生成时已经写死了 utf-8, 没有 charset 配置项可调。

所以如果你加了 charset: utf-8 却没效果 —— 因为这个配置项不存在, 加了也是被忽略。

真出现乱码, 查这两处:

1. 文章源文件本身的编码是不是 UTF-8(GBK 存的中文站点很容易踩)
2. description 字段里有没有非法字符 —— XML 里的 & 必须写成 &, 直接放裸的会让整个订阅源解析失败

想让订阅源只显示摘要而不是全文

没有 excerpt 这个配置项(网上部分教程写错了)。控制全文还是摘要的开关叫 content, 默认 true(输出全文):

1
2

feed:
  content: false

content: false 时, 每篇文章只输出摘要 —— 摘要优先取文章 front-matter 里的 description, 没有就取 excerpt, 都没有就截取正文前 content_limit 个字符(默认 140)。

想让摘要长一点:

1
2
3

feed:
  content: false
  content_limit: 300

全文订阅的好处是阅读器不跳转到你的站点, 体验好、也不会消耗你的服务器流量。摘要模式则相反, 能给站点导流。

两种都试试, 看看哪个数据好。

一个容易被忽略的点: RSS 也是 SEO 利器

前面提到 RSS 能加速收录, 这里展开说一下。

搜索引擎的爬虫会定期抓取你的 RSS。因为 RSS 里是纯文本 + 结构化的新文章链接, 比解析 HTML 页面高效得多。

而且 RSS 文件是静态的, 没有 JS 渲染的负担。百度对 JS 的处理能力本来就弱, RSS 相当于给它提供了一条不需要执行 JS 的抓取路径。

所以我的建议是:

1. 务必开启 RSS
2. 别忘了 autodiscovery: true —— 插件会自动往每个页面的 <head> 里插一条 <link rel="alternate" type="application/atom+xml">, 浏览器的”订阅此页”和大部分阅读器的自动发现都靠它, 这是最省事也最有效的入口
3. robots.txt 里指向 sitemap(RSS 是自动发现的, 不用单独写)
4. 保持 entry 的 updated 字段准确 —— 很多搜索引擎会把它当作内容新鲜度的信号

小结

接入 RSS 其实是 5 分钟的事:

1. npm install hexo-generator-feed --save
2. _config.yml 配 feed: 段(type 和 path 都写成数组, 注意是 rss2 不是 rss)
3. 重新构建, 确认 public/atom.xml 和 public/rss.xml 都生成了
4. 侧边栏加 RSS 图标(_config.butterfly.yml 的 social 加一行, 零代码改动, 全页可见)
5. 想要更醒目的转化, 再改 themes/butterfly/layout/post.pug 加文章底部按钮(主题本身不带 RSS 功能, 别去找 rss: 配置)
6. 提交到 Feedly / Inoreader 等平台

别小看这个文件。 它是静态博客里少数几个”让读者主动回访”的通道, 而且几乎没维护成本 —— 装一次插件, 之后每次构建自动更新。

最后提一个坑: 如果你的站点文件托管在对象存储/CDN 上, 不存在的文件可能不会返回 404,而是返回一个 200 的错误页(我们遇到的就是返回一张 16KB 的 JPEG 图片)。这种环境下, 别人提交你的 RSS 地址时, 对方会拿到图片而不是 XML, 直接判定订阅源无效。所以 RSS 上线后一定要自己 curl 一次, 确认拿回来的是 <?xml 开头的真 XML。

参考链接:

• hexo-generator-feed - GitHub
• W3C Feed Validator
• Butterfly 主题文档

前言

写 Hexo 文章多了之后, 会遇到一个共同的问题: 报错信息看不出到底哪里错了。

比如 hexo s 突然起不来, 或者构建出来的东西和预期不一样。网上的解决办法五花八门, 试一圈下来问题还在。

这篇不讲具体某个错误的怎么修, 而是讲一套固定的排查顺序 —— 先排除掉最常见、最容易被忽略的原因, 再往深处查。按这个顺序走, 大部分问题在第 1、2 步就能定位。

排查总览

先给个全貌, 后面逐条展开:

顺序很重要。大部分人一开始就去改配置, 结果改了半天, 其实是缓存脏了。

第一步: 清干净缓存重装

为什么必须先做这步

Node 生态有个很坑的地方: 改了配置但不重装, 行为不会变。

node_modules 里装的是旧版本, 缓存里存的是旧的中间结果。这两个不清掉, 你后面所有的排查都是在验证一个错误的环境。

而且如果你之前在 Node 18 下装过依赖, 现在换到 Node 20, 那些原生模块(native module)是按旧版本编译的, 直接拿来用大概率出问题。

标准操作

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 1. 清缓存和生成产物
hexo clean

# 2. 删掉依赖锁文件和依赖目录
# Linux / macOS
rm -rf node_modules package-lock.json
npm cache clean --force

# Windows PowerShell
Remove-Item -Recurse -Force node_modules
Remove-Item -Force package-lock.json

# 3. 重新安装
npm install

# 4. 验证
hexo g
hexo s

注意 package-lock.json 也要删。它的作用是锁定依赖版本, 但如果你要解决的问题正是”依赖版本不对”, 那这份锁定文件就是问题的固化 —— 必须删掉让它重新解析。

判断: 这步有没有用

做完这一步就好了, 说明问题出在依赖残留。以后遇到构建问题, 直接从这步开始, 能省很多时间。

第二步: 查依赖树找冲突源

如果第一步做完还是报错, 说明是真实的依赖冲突, 得往下查。

找出某个包到底装了几个版本

这是排查依赖冲突最有用的一条命令:

1

npm ls strip-ansi

输出会明确告诉你哪些包依赖了它、装的是什么版本:

1
2
3
4
5
6
7

zsyyblog@
├── hexo@8.1.0
│   └── hexo-util@4.x
│       └── strip-ansi@7.1.0
└── hexo-butterfly-envelope@1.0.13
    └── some-old-plugin@0.8.2
        └── strip-ansi@6.0.1

看到同一个包同时存在 7.x 和 6.x, 就知道问题在哪了。

ERR_REQUIRE_ESM 怎么定位

如果报这个错:

1

Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported

排查步骤:

1
2
3
4
5
6

# 1. 看报错里的路径, 记下具体是哪个包
# 2. 查这个包在依赖树里的位置
npm ls <包名>

# 3. 查它的版本和模块类型
cat node_modules/<包名>/package.json | grep -E '"version"|"type"'

关键看 "type" 字段:

• "type": "module" —— ESM, 不能被 require()
• 没有 "type" 或 "type": "commonjs" —— CommonJS, 可以被 require()

解决办法: 强制降级传递依赖

如果确认是某个包的新版本把老插件搞崩了, 在项目根目录强制装一个旧版本:

1

npm install <包名>@<兼容版本> --save-exact

--save-exact 会把版本号精确锁定(不带 ^), 这样它会作为直接依赖被放在项目根目录, 所有传递依赖都会优先找到它。

Hexo 升级时最常见的组合是:

1

npm install strip-ansi@6.0.1 --save-exact

第三步: 换 Node 版本验证

为什么换版本能定位问题

有些报错很奇怪, 同一个代码在 A 机器上正常, 在 B 机器上就炸。这类问题九成是 Node 版本差异。

Hexo 各版本对 Node 的要求:

如果你的 Hexo 8 项目跑在 Node 18 上, 很多报错都是版本不对导致的, 而不是配置错误。

用 nvm 管理版本

安装 nvm:

1
2

# Linux / macOS
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

常用命令:

1
2
3
4
5

nvm install 20        # 安装 Node 20
nvm install 22        # 安装 Node 22
nvm use 20            # 切到 Node 20
nvm ls                # 查看已安装版本
nvm current           # 查看当前版本

Windows 上推荐用 fnm, 体验和 nvm 一致。

换版本后必须重装依赖

这是最容易漏的一步:

1
2
3
4
5
6
7

nvm use 20

# 必须重装, 不能直接用旧依赖
rm -rf node_modules package-lock.json
npm install

hexo clean && hexo s

因为原生模块是针对特定 Node 版本编译的, 换了 Node 不重装, 大概率会报 NODE_MODULE_VERSION 不匹配。

判断: 是不是版本问题

做法很简单: 换到另一个 Node 大版本, 重新完整安装, 看问题是否消失。

• 消失 → 确定是版本问题, 把版本固定下来
• 还在 → 版本不是主因, 继续第四步

把版本固定下来

确认可用后, 在 package.json 里声明, 避免以后重装又变:

1
2
3
4
5

{
  "engines": {
    "node": ">=22 <25"
  }
}

装了 nvm 的话, 还可以配一个 .nvmrc 文件, 内容就是版本号:

1
2

echo "22" > .nvmrc
nvm use

第四步: 排除插件影响

前三步做完还报错, 大概率是某个插件的问题。

二分法定位

最朴素但最有效的办法: 逐个禁用插件。

先在 package.json 里把可疑插件注释掉, 重新安装构建:

1
2
3
4

# 禁用后重装
rm -rf node_modules package-lock.json
npm install
hexo clean && hexo g

如果好了, 就是这个插件的问题。再装回来。

更快的办法: 看报错来源

多数情况下报错信息本身就指向了来源, 比如:

1
2
3

Error: Cannot read properties of undefined (reading 'cover')
#                        ^^^^^^
# 这里读的是 cover 字段, 去 grep 谁在读 cover

1
2

npm ls <报错里的包名>
# 输出会告诉你这个包是被谁引入的

1
2

# 直接在源码里搜
grep -r "<出错的字段名>" themes/ node_modules/<可疑包>/

临时绕过

如果确认是插件 bug 但急着发文章, 可以用垫片绕过, 而不是改插件源码。

比如老插件调用的全局函数在新版里被搬走了:

1
2
3
4

// 在 _config.butterfly.yml 的 inject.head 里加
window.getScript = window.getScript || function(u, a) {
  return window.btf.getScript(u, a)
}

用 || 做存在性判断, 这样即使主题以后又把函数放回去了, 这段代码也不会冲突。

第五步: 动配置

到这一步基本可以确定是配置问题了。

Hexo 配置的排查要点:

配置层级要看清

Hexo 的配置有主题配置和站点配置两套, 同时还存在 _config.yml(站点)和 _config.butterfly.yml(主题)的区别。

常见误区: 把站点配置写到了主题配置里, 或者反过来。先确认你改的文件是哪个。

缩进和类型

YAML 对缩进敏感, 这几个错误很常见:

1
2
3
4
5
6
7
8
9
10
11
12
13

# 错: tab 缩进(YAML 不支持 tab)
inject:
head:
  - xxx

# 错: 布尔值写成字符串
enable: 'true'      # 这是字符串 "true"
enable: true        # 这才是布尔值

# 错: 列表项缩进不对
inject:
  head:
  - xxx             # 应该再缩进两格

插件的配置节点可能缺失

老插件升级后, 配置格式可能变了。报错里出现 undefined 时, 优先怀疑配置节点缺失。

一个通用的排查习惯

最后说一个我觉得最有用的习惯 —— 每次排查都记录下来。

我自己的做法是, 每解决一个新报错, 就写成一篇博客:

1. 报错现象是什么
2. 根因是什么
3. 怎么解决的
4. 参考链接

这样做有三个好处:

• 下次遇到同类问题, 直接搜自己的文章, 不用重新推导
• 一年后回头看, 这些文章正好是最有搜索价值的踩坑记录
• 排查过程被迫理清一遍, 记忆反而更牢

排查本身是隐性的, 写出来才是显性的知识。

小结

一套固定的排查顺序, 记住这五步:

1. 清缓存重装 —— 排除依赖残留(最常见)
2. 查依赖树 —— npm ls <包名> 找冲突源(第二常见)
3. 换 Node 版本 —— 排除版本错配
4. 排除插件 —— 二分法禁用 + 看报错来源
5. 最后动配置 —— YAML 缩进、类型、节点缺失

核心原则: 从最常见的原因查起, 不要一上来就改配置。

绝大多数构建问题在第 1、2 步就解决了, 而大部分人恰恰是从第 5 步开始的 —— 于是改了半天配置, 问题根本不在那里。

参考链接:

• Node.js Releases
• npm 依赖树文档
• Hexo 文档 - 常见问题

前言

上一篇文章写了 Hexo 7 → 8 的升级, 这次接着记录 Butterfly 主题的升级。

本地是 5.2.2, 当前最新是 5.7.0。中间跨了 5.3、5.4、5.5、5.6、5.7 五个版本, 官方更新日志里有大量性能优化和 bug 修复, 值得升级。

但升级过程中踩到了几个坑, 其中一个是跨大版本的破坏性变更, 老插件直接罢工。这篇把过程和解决办法记下来。

先看升级收益

翻了一遍 5.6 的更新日志, 对博客体验提升比较明显的有这些:

• TOC 目录滚动从 throttle 轮询换成 IntersectionObserver, 大幅减少滚动事件的计算量
• 滚动处理器换成 btf.rafThrottle, 跟随浏览器渲染帧率
• 平滑滚动从线性插值改成 easeOutQuart 缓动, 观感更自然
• 新增 scriptCache / cssCache 机制, 防止脚本和样式重复加载
• Mermaid 手势系统用 AbortController 重写, 修复了 Chrome 下滚动图表乱跳
• 修复 flink.js 和 button.js 缺少 HTML 转义导致的 XSS 漏洞

性能优化是实打实的, 文章多了之后尤其明显。

障碍一: ReferenceError: getScript is not defined

这是最典型的报错, 说说组件加载不出来(比如”说说”模块)。

报错现象

1

ReferenceError: getScript is not defined

页面上对应组件的位置空白, 控制台一片红。

根因: 全局函数搬进了命名空间

Butterfly 3.x 时代, getScript 是直接挂在 window 上的:

1

window.getScript = ...

所以任何地方都能直接调。

从 5.x 开始, 这类函数被收进了 window.btf 命名空间:

1

window.btf.getScript = ...

而我用的那个第三方插件(信封/说说相关), 它注入的内联脚本里调的还是裸函数:

1

getScript('/js/xxx.js', callback)

这个裸调用现在自然就找不到了。

解决办法: 加一段惰性垫片

不想改插件源码的话, 可以在 inject.head 里加一段垫片代码。关键在于”惰性” —— 调用的时候才去取 btf, 这样就不依赖脚本的加载顺序:

1
2
3

window.getScript = window.getScript || function(u, a) {
  return window.btf.getScript(u, a)
}

六行代码, 一个插件都不用改。

具体做法是在 _config.butterfly.yml 的 inject.head 下面加:

1
2
3
4
5
6

inject:
  head:
    - |
      window.getScript = window.getScript || function(u, a) {
        return window.btf.getScript(u, a)
      }

这个思路挺通用的 —— 遇到”全局函数搬家”导致的报错, 都可以用同样的方式兜一层。

障碍二: 构建直接崩, 报 cover undefined

报错现象

1

TypeError: Cannot read properties of undefined (reading 'cover')

hexo g 直接中止, 构建不出来。

根因: 插件配置节点缺失

hexo-butterfly-envelope 从 1.0.13+ 开始, 把四张图片收进了 custom_pic 这个子节点里, 而代码内部不做任何存在性检查就往下读。

我的旧配置里没有这一节, 于是读 undefined.custom_pic, 构建直接崩。

解决办法: 补齐配置节点

按插件要求补上配置就行:

1
2
3
4
5
6
7

envelope:
  enable: true
  custom_pic:
    pic_1: xxx.png
    pic_2: xxx.png
    pic_3: xxx.png
    pic_4: xxx.png

补的时候顺手发现, 它的默认值还指向一个已经废弃的镜像地址, 一并改成了自己的图床。

教训: 老插件升级后如果直接崩, 先去看它的 changelog, 大概率是配置格式变了。

障碍三: unknown block tag: timenode

报错现象

1

ERROR Failed to render tag: unknown block tag: timenode

文章渲染失败, 但不是全部文章, 只有用了特定标签的那几篇。

根因: 同名标签, 少注册了一个

Butterfly 5 自己带了一个 timeline 标签, 但只注册了这一个。

而我用的第三方版本除了 timeline, 还注册了 timenode。我的文章里用了 30 次 timenode, 于是就报错了。

解决办法: 保留第三方版本

让第三方的标签插件覆盖官方的, 这样两个标签都能用。

这个问题的本质是同名标签的注册冲突 —— 如果你升级后遇到”某个标签突然不认识了”, 先想想是不是两个插件抢同一个标签名。

升级前: 先验证挂载点

这次升级前我做了件事, 差点白做。

我原本的判断是: 跨 5 个版本, 那些插件依赖的模板挂载点肯定早被删了, 升级必然失败。

于是我把 5.7.0 的包解开, 直接 grep 那几个挂载点:

1
2

# 解包后 grep 挂载点
grep -r "recent-posts\|sticky_layout\|aside-content\|card-widget" layout/

结果如下:

四个挂载点在新版里一个不少, 而且 card-widget 还多了 2 个。

所以我那条”最重的理由”—— 证据不支持。改口之后, 升级才真正开始。

这一步花的时间不长, 但避免了”因为一个不成立的判断而放弃升级”。预感值得说出来, 但只有证据能定案。

完整升级流程

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 1. 备份 + Git 基线
git add -A && git commit -m "baseline: pre-butterfly-5.7"

# 2. 记录当前版本, 方便对比
cat themes/butterfly/package.json | grep version

# 3. 升级主题
npm install hexo-theme-butterfly@5.7.0 --save

# 4. 补齐插件配置节点(envelope 的 custom_pic)
# 5. 加 getScript 垫片到 inject.head
# 6. 验证
hexo clean && hexo g
hexo s

建议的版本锁定

升级完记得把版本锁进 package.json, 避免以后重装得到不同环境:

1
2
3
4
5
6
7

{
  "dependencies": {
    "hexo": "8.1.0",
    "hexo-theme-butterfly": "5.7.0",
    "hexo-butterfly-envelope": "1.0.13"
  }
}

小结

这次跨越 5 个小版本, 全过程只撞到 3 个真实障碍, 比预期少很多:

1. getScript 搬家 —— 用惰性垫片兜住, 不改插件源码
2. 配置节点缺失 —— 补配置即可
3. 同名标签冲突 —— 让第三方版本覆盖官方

三个问题的共同点是: **都不是主题本身的 bug, 而是”老插件跟不上新主题”**。

所以升级前做的那件事 —— grep 挂载点验证 —— 比事后一个一个试错要高效得多。

参考链接:

• Butterfly 5.6 Release Notes
• hexo-theme-butterfly - GitHub

前言

最近整理博客依赖, 发现本地还是 hexo 7.3.0, 而官方已经发布到 8.1.0 了。中间隔着 8.0.0 这个大版本, 时隔一年多(2024-07 → 2025-09), 不少东西都变了。

这篇记录一下升级过程中踩到的坑, 供同样在使用 Hexo 的朋友参考。

先说结论: 升级本身不难, 难的是 Node 版本和插件生态的错配。

版本现状对照

在动手之前, 先看清楚自己站在哪里:

查版本和发布日期:

1
2
3
4
5
6
7
8

# 查看本地 hexo 版本
npx hexo version

# 查看主题版本
cat themes/butterfly/package.json | grep version

# 查看 node 版本
node -v

也可以直接看官方 hexo.io 首页的 Releases 列表, 版本发布时间写得很清楚。

第一个坑: Node 版本不达标

官方 breaking change

Hexo 8.0.0 的 release note 里, Breaking Changes 一栏只有两条, 但都很硬:

• chore: drop Node.js 16
• chore: drop Node.js 18

也就是说, Hexo 8 要求 Node.js 20.19.0 或更高版本。

如果你的环境还是 Node 16 或 18, 升级 Hexo 之后大概率会直接报错, 或者在装依赖的时候就一堆 warning。

检查自己的 Node 版本

1
2

node -v
npm -v

如果版本号开头是 v16. 或 v18., 那就必须先升级 Node, 再动 Hexo。

我这里用的是 Node 22.22.2 LTS, 直接满足要求, 所以没踩这一步。如果你恰好还在 18 上, 请务必先升 Node, 不要直接升 Hexo, 否则排查方向会完全跑偏。

第二个坑: ERR_REQUIRE_ESM

这是我看到的最高频的一个报错:

1
2
3

npm install
# 或者 hexo g 时
Error [ERR_REQUIRE_ESM]: require() of ES Module ... from ... not supported

根因分析

这不是 Hexo 本身的问题, 而是一个依赖版本错配问题。

Hexo 8 把很多底层依赖都往上提了一轮, 比如 hexo-util 从 3 提到 4。而一些老的第三方插件并没有跟着更新, 它们内部还依赖着旧版的 strip-ansi。

关键在于 strip-ansi 这个包的版本差异:

• strip-ansi@6.x —— CommonJS, 可以被 require()
• strip-ansi@7.x —— 改成了 ESM, require() 会直接报错

新版 Hexo 依赖链里会带进 strip-ansi@7, 而老插件内部还在用 require() 加载它, 于是就撞上了。

解决办法

思路是在你的项目里强制降级这个传递依赖, 让老插件能找到它认识的格式:

1

npm install strip-ansi@6.0.1 --save-exact

这条命令会在你的项目根目录放一个”旧版零件”, 所有插件都能拿到, 从而避开 ESM 冲突。

验证

1
2

hexo clean
hexo s

如果 hexo s 能正常起服务, 说明问题解决了。

第三个坑: 别用 npm update

这是习惯问题, 但影响很大。

以前升级 Hexo 我习惯用 npm update, 这次没有继续这么做。原因是 npm update 会把范围内所有依赖都往最新拉, 一旦某个中间包出了不兼容的版本, 排查起来非常痛苦。

更稳妥的做法是在 package.json 里锁定关键依赖的主版本:

1
2
3
4
5
6
7
8
9

{
  "engines": {
    "node": ">=22 <25"
  },
  "dependencies": {
    "hexo": "8.1.0",
    "hexo-theme-butterfly": "5.7.0"
  }
}

这样以后删掉 node_modules 重新安装, 得到的是同一套环境, 不会因为”今天装的和上次装的不是一个东西”而困惑。

顺便说一句, engines 这个字段很值得加, 它能在安装阶段就提醒你 Node 版本对不对。

升级前的准备: 两层回退

升级这种事, 备份不是可选项。

我给自己的博客目录建了两层回退:

第一层: Git 基线

1
2
3
4
5

git init
git add -A
git commit -m "baseline: pre-Hexo-8"
git tag pre-hexo8
git switch -c upgrade/hexo-8

好处是任何配置和源码问题都能用 Git 直接定位和回滚。

第二层: 完整压缩包

博客目录里除了 source/, 还有 node_modules/、生成的 public/、部署用的 .deploy_git/, 以及主题目录里的 Git 历史。这些东西 Git 不好管, 建议打一个完整压缩包。

1
2
3
4
5

# 以 Linux 为例
tar -czf hexo-backup-$(date +%Y%m%d).tar.gz --exclude=node_modules .

# Windows PowerShell
Compress-Archive -Path . -DestinationPath hexo-backup-20261021.zip

打完包之后, 建议算一下 SHA-256 校验值, 确认压缩包真的能解开, 而不是坏在那儿了。

完整操作流程

把上面的步骤串起来:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

# 1. 确认当前版本
npx hexo version
node -v

# 2. 备份(别跳过这步)
# 打压缩包 + 算校验值

# 3. Git 基线
git add -A && git commit -m "baseline: pre-Hexo-8"

# 4. 切换分支, 开始升级
git switch -c upgrade/hexo-8

# 5. 升级 Hexo
npm install hexo@8.1.0 --save

# 6. 如果报 ERR_REQUIRE_ESM, 强制降级
npm install strip-ansi@6.0.1 --save-exact

# 7. 验证
hexo clean
hexo s

关于主题的兼容问题

这里要单独提一句: Hexo 升级和主题升级最好分开做, 不要一次全升。

原因是主题的模板文件可能依赖特定版本的 Hexo API。我见过 Hexo 一升级, 主题直接报模板渲染错误的。

建议的顺序是:

1. 先只升 Hexo, 主题不动, 看能不能正常构建
2. 确认没问题了, 再单独升主题
3. 每一步都做 Git 提交, 出问题好回退

如果你和我一样用 Butterfly, 可以参考这篇 [从 3.7.1 升级到 5.7.0 的真实障碍], 官方更新日志写得很细。

几个已经废弃的配置项

顺手记一下, 升级时如果看到相关报错, 可能是这几个旧配置引起的:

小结

这次升级的核心体会就三条:

1. 先看版本, 再动手。Hexo 8 的门槛是 Node 20.19.0+, 版本不够就先升 Node。
2. 报错先看依赖树, 不要瞎改。ERR_REQUIRE_ESM 绝大多数是 strip-ansi 的锅, 降级即可。
3. **锁定主版本, 别用 npm update**。可复现的环境能省掉大量重复排查。

升级本身花不了多少时间, 真正花时间的是”出问题之后不知道从哪查”。所以第 2、3 条更重要。

参考链接:

• hexo 8.0.0 Released
• Hexo Releases - GitHub
• Butterfly 更新日志

前言

为了适应当下的协作开发的节奏, svn的时代渐行渐远, git的操作无疑让开发进度更加快速。 于是乎 svn->git是必然的的, 而且还要带上提交记录, 进行无缝切换。

基本技能

阅读以下操作, 默认你已经具备一下技能和环境:

1. Gitee/Github/Gitlab线上仓库(本文已gitee为例)
2. HomeBrew(这个可以使用别的, 主要是安装3-5)
3. git
4. svn
5. git-svn(这个是重点)

可选:

ssh公钥

如果在安装环境和软件过程中, 出现问题, 请自行百度, 这里不做赘述。

步骤概览

1. 获取svn所有提交记录的操作者名单, 替换成分配的账号
2. git-svn处理, 拉取svn项目,并创建git
3. 设置git仓库地址
4. 推送上去

前提说明

本文意在指导操作步骤, 至于操作细节, 请根据项目实际操作。
我将进行操作, 将以前的多人项目svn移步到我的个人git上。

详细步骤

服务器获取svn提交者记录

找你们的服务器给你一个, 自行需求到满足格式的形式

本地获取svn提交者记录

如果你通过5.1步骤拿到了, 请忽略

• 本地新建文件夹, 作为处理仓库

• 新建userinfo.txt

• cd到当前文件夹

• git clone svn项目地址 到当前文件夹下

• 执行命令:
  这里注意,前言中说明了, 这里主要是转移到我的个人仓库, 所以, xxx的位置需要填写我的仓库邮箱地址

  1	svn log -r 1:HEAD --xml | grep "' '{print $2}' | awk -F '' '{print $1"="$1"<xxx>" }' > userinfo.txt

• 通过上述代码得到所有提交者记录, 并进行了格式化, 可以根据实际情况做映射改动

git-svn转换

• 新建一个全新的文件夹, 作为转换的仓库
• 将5.1或者5.2获取到的userinfo.txt复制到当前文件夹下
• cd到当前文件夹
• 执行命令

  1 2	// xxx为你的svn地址, 请自行填写 git svn clone xxx --no-metadata --authors-file=userinfo.txt

  这期间如果出现什么问题, 请自行百度, 大概率是git-svn的安装问题

创建网络仓库

这里采用的是gitee

• 新建一个空仓库, 不需要选择其他的东西, null null null
• 接下来你会看到仓库的提示, 这里就选择普通的https的模式

配置本地信息

我们继续回到步骤5.2中新文件夹
此时该文件夹下, 一个项目文件, 一个userinfo.txt

依次执行一下命令:

1
2
3
4
5
6
7
8
9
10
11

(1) 创建readme文件
touch README.md

(2) git添加提交文件
git add README.md

(3) 这里xxx是步骤3中的https的地址
git remote add origin xxx

(4) 推送上去
git push -u origin "master"

1. 新建文件夹SVN_TO_GIT（随意命名），进入文件夹

2. 执行命令

   1 2 3

   cd SVN_TO_GIT git svn clone --authors-file=authors.txt SVN代码库地址

   authors.txt文件保存svn用户与git用户的对应关系，如下所示:

   1	svn用户=git用户名(邮箱地址)

3. （可选步骤）如果SVN项目有忽略文件，进入项目(project)文件夹，执行如下命令转换SVN:ignore属性为 .gitignore文件。

   1 2 3 4 5

   cd ./project git svn show-ignore > .gitignore git add .gitignore git commit -m 'Convert svn:ignore properties to .gitignore.'

4. （可选步骤）如果clone完成后，SVN仓库还有更新，可执行以下命令同步SVN更新

   1	git svn rebase

5. 添加git远程仓库地址，前提必须是空库

   1	git remote add origin Git代码库地址

6. 推送代码

   1	git push -u origin master

准备工作

打开命令行提示符，输入以下命令：

1

svnlook youngest d:/SVNRepository

查看当前最新的版本号，显示最新版本记录为755。

备份版本库

很重要，在尝试过程中出现过失败，幸亏有备份，不然就over了

把D盘的版本库，备份到C盘，同时清除历史日志，输入命令：

1

svnadmin hotcopy --clean-logs d:/SVNRepository c:/SVNRepository

这样备份后版本库从3.34G变为3.24G。

dump需要保留的版本

输入以下命令：

1

svnadmin dump c:/SVNRepository -r 745:755 > d:/repo_dump_745_755.dmp

3.24G的版本库dump出来后变成760M，苗条不少。

删除旧版本库

输入以下命令：

1

rmdir /s/q d:/SVNRepository

删除旧版本库，也可以直接在资源管理器里删除。

创建空的版本库

输入以下命令：

1

svnadmin create d:/SVNRepository

检查空的版本库大概31.2K大小。

把dump文件导入版本库

输入以下命令：

1

svnadmin load d:/SVNRepository < d:/repo_dump_745_755.dmp

这时屏幕上会显示正在载入版本库中的文件或正在提交/装载的版本。

完成后，用命令svnlook youngest d:/SVNRepository 查看，显示当前版本库最新版本号是11，整个版本库大小501M。

参考链接：https://blog.csdn.net/cfl2011/article/details/78772564

报错信息

svn 查看历史记录失败 ，并提示’Item is not readable’，如下图所示：

解决方法

1. 修改 svnserve.conf配置文件

   1	anon-access = none

   设置anon-access = none就可以了

2. 或者修改authz

   1

   * = r

背景

最近在VS中使用到了宏定义，结果宏名开头显示出 “…”，并显示出“宏可以转换为constexpr”，如果想屏蔽掉这个提示按照下面的方法操作即可解决

解决办法

1. 在“工具->选项”菜单中，导航到“文本编辑器->C/C++->查看”
2. 在右侧找到“代码波形曲线”其中的“可转换为constexpr的宏”中选择“无”。

问题描述

每次在我的项目中使用任何宏名称时，都会出现3个点加下划线的提示，如下图所示：

​
当我将鼠标悬停在它上面时，会出现一个灯泡和一个小消息框，提示在这个标识符周围浏览可能是不正确的，并建议将此宏添加到一个提示文件中，该文件似乎没有任何作用：

​

解决办法

1. 在“工具->选项”菜单中，导航到“文本编辑器->C/C++->查看”
2. 在右侧找到“代码波形曲线”其中的“已跳过的浏览区域中的宏”中选择“无”。

问题概述

在使用JavaScript进行AJAX请求时，你可能会遇到“Origin null is not allowed by Access-Control-Allow-Origin”错误。

当浏览器从文件系统URL发送请求时，它会将来源（origin）设置为“null”。

然而，许多网站限制了哪些来源可以访问它们的资源，从而导致此错误发生。

解决方法

为了解决这个问题，我们需要修改请求方式，以避免将来源设置为“null”。

使用JSONP

将你的请求更改为使用JSONP（JSON with Padding）格式。JSONP允许你使用 <script> 标签来请求数据，这会绕过同源策略限制。

修改后的代码如下：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16