博客接入 Artalk 评论系统

2026-05-16

博客 / Artalk

ai 总结的

部署#

在 1Panel 用 Docker 部署 Artalk，挂载数据目录，映射端口 2988。

后台 /sidebar/ 可以访问，创建站点 GTLX Blog。

踩坑记录#

坑 1：API 路径 v1 vs v2#

前端一直报 fetch error，curl 测试 /api/v1/comment 也 404。

查了 Artalk 前端的 JS 才发现——v2.9.1 的 API 路径是 /api/v2/，不是 v1。

而且接口名区分单复数：

/api/v2/comment → 404
/api/v2/comments → 200

坑 2：CORS 跨域#

博客 localhost:4321 和 Artalk 1.12.49.90:2988 不同源，浏览器拦截。

Artalk 的 trusted_domains 配置需要写具体域名（含协议和端口）：

1
trusted_domains:
2
  - http://localhost:4321
3
  - https://gtlx.ltd

通配符 "*" 在这个版本不生效。配置后要重启容器。

验证方式：

1
curl -D - -H "Origin: http://localhost:4321" http://your-server/api/v2/comments?page_key=/&site_name=GTLX%20Blog | grep Access-Control

坑 3：构造函数参数名#

Artalk v2.9.1 的构造参数是 server，不是 serverURL。

错误的代码导致 server 字段为空，API 请求走了相对路径 /api/v2/conf 到博客自身，返回 404。

正确写法：

1
new Artalk({
2
  el,
3
  server: "http://1.12.49.90:2988",
4
  site: "GTLX Blog",
5
})

坑 4：容器端口变化#

第一次重启容器后，Artalk 内部监听端口从 23366 变成了 2988，1Panel 的端口映射没改过来，导致连不上。

加环境变量 ARTALK_PORT=23366 恢复。

坑 5：CSS 被动态注入，主题样式无法覆盖#

import Artalk from "artalk" 后，Artalk 内部会将 CSS 动态注入到 <body> 末尾，优先级高于 Astro 打包在 <head> 的主题样式。导致自定义覆盖规则无效。

解决：在 Layout.astro 中显式导入 CSS，使其与主题样式同层级打包进 <head>：

1
import "artalk/dist/Artalk.css";

但 Artalk JS 在运行时仍可能额外注入样式覆盖 <head> 中的规则。因此还需要两层防御：

CSS 加载顺序：override 文件在 Artalk.css 之后导入：

1
import "artalk/dist/Artalk.css";
2
import "@shared/styles/artalk-override.css";

!important 标记：override 中关键规则加 !important，确保即使 JS 后续注入新的 <style> 也无法覆盖：
```
1
.atk-comment-wrap {
2
  background: var(--card-bg) !important;
3
  border-radius: var(--radius-large) !important;
4
}
```
核心原则：显式导入 CSS 进 <head> + <head> 内同层级控制先后顺序 + 关键规则 !important，这三层配合可以完全管控 Artalk 的视觉表现。

坑 6：`define:vars` 与 `import` 不兼容#

在 Astro 的 <script> 中同时使用 define:vars 和静态 import，会导致脚本不执行，评论区空白且无报错。

解决：用 data- 属性传参代替 define:vars：

1
<div id="artalk-container" data-server={serverUrl} data-site={site}></div>
2

3
<script>
4
import Artalk from "artalk";
5
const el = document.getElementById("artalk-container");
6
const at = new Artalk({
7
    el,
8
    server: el.getAttribute("data-server"),
9
    site: el.getAttribute("data-site"),
10
});
11
</script>

坑 7：SPA 导航下不重新初始化#

项目使用 @swup/astro 做无刷新导航，页面切换后 Artalk 实例仍挂载着旧 DOM，评论区空白。

解决：通过事件驱动重新挂载：

1
// MainGridLayout.astro — 每次页面切换后派发事件
2
document.addEventListener("swup:contentReplaced", () => {
3
    document.dispatchEvent(new Event("loadComment"));
4
});
5

6
// CommentSystem.astro — 监听事件重新初始化
7
document.addEventListener("loadComment", loadArtalk);