Icarus用户指南 - 用户评论插件

本文介绍Icarus支持的用户评论插件的安装配置。

本文同时提供以下语言的翻译：English。

下面的用户评论插件由ppoffice/hexo-component-inferno提供，完整的支持插件列表和配置详情以其为准。

Artalk

Artalk是一个自建的评论系统。 和Isso、Twikoo一样，在Icarus中使用它之前，你需要自己运行Artalk服务端。

安装指南

1. 按照Artalk文档部署Artalk服务端，并在其中添加你的站点。

2. 将Artalk服务端的地址和你的站点在服务端上的名称填入主题配置中：

   _config.icarus.yml

   comment:
       type: artalk
       server: https://artalk.example.com  # 必填项。Artalk服务端的地址
       site: My Blog                       # 可选填。站点在Artalk服务端上的名称
       locale: zh-CN                       # 可选填。Artalk的语言，如en、zh-CN或auto
       prefer_remote_conf: false           # 可选填。为true时优先使用Artalk服务端上的配置
       # dark_mode: auto                   # 可选填。true、false或auto。不设置时跟随页面外观

3. 注意事项：

   • 不设置dark_mode时，Artalk会跟随页面的外观：设置appearance: dark时为暗色，设置appearance: auto时跟随访客系统的配色。 将dark_mode设置为true、false或auto（跟随系统配色）可以覆盖这一行为。
   • Artalk通过页面的路径来区分各个页面的评论。 你可以在页面的front-matter中把page_key设置为该页面的其他唯一标识，例如在移动页面后保留评论。 由于front-matter会替换整个comment配置，请把其他评论配置项也一并复制过去。
   • 请使用与2.10.0版本客户端兼容的Artalk服务端。
   • 关于这些配置项的详细说明，请参考Artalk客户端配置。

Beaudar

Beaudar是utterances的中文分支，它把评论保存在GitHub issue中。 它的设置过程与utterances相似。

安装指南

1. 准备一个公开的GitHub仓库(Repository)，并按照Beaudar文档在这个仓库上安装Beaudar的GitHub应用。

2. 将仓库等信息填入主题配置中：

   _config.icarus.yml

   comment:
       type: beaudar
       repo: Your-GitHub-Username/Your-Public-Repo-Name
       issue_term: pathname        # 必填项，与issue_number二选一填写
       # issue_number: 100         # 必填项，与issue_term二选一填写
       branch: main                # 可选填。存放beaudar.json的仓库分支
       label: some-issue-label     # 可选填
       theme: github-light         # 可选填，默认为github-light。页面为亮色时使用
       dark_theme: github-dark     # 可选填，默认为github-dark。页面为暗色时使用

3. 注意事项：

   • issue_term（如pathname、url或title）和issue_number必须且只能设置一个，两个都设置会导致配置检查失败。
   • theme在页面为亮色时使用，例如github-light、github-dark或preferred-color-scheme。 dark_theme在页面为暗色时使用，即设置了appearance: dark，或者设置了appearance: auto且访客的系统使用暗色配色时。 它的取值包括github-dark、github-dark-orange、classic-dark、dark-blue、icy-dark和photon-dark。

畅言

安装指南

1. 首先，登录畅言云评， 并按照PC端通用代码接入文档获取评论HTML代码。

2. 复制appid与conf的值到主题配置的对应配置项中。 例如，如下的HTML代码：

   畅言安装代码 >folded

   <!--PC版-->
   <div id="SOHUCS" sid="..."></div>
   <script charset="utf-8" type="text/javascript" src="https://cy-cdn.kuaizhan.com/upload/changyan.js" ></script>
   <script type="text/javascript">
   window.changyan.api.config({
       appid: '????appid????',
       conf: 'prod_xxxxxxxxxxxxxxxxxxxxxxx'
   });
   </script>

   对应到主题配置为：

   _config.icarus.yml

   comment:
       type: changyan
       app_id: ????appid????
       conf: prod_xxxxxxxxxxxxxxxxxxxxxxx

Disqus

安装指南在线预览

1. 首先，登录Disqus。 点击首页的“开始”(GET STARTED)按钮或者访问 此处并点击“我想要将Disqus安装到我的站点” (I want to install Disqus on my site)来创建新的站点评论服务。

   
   

2. 在创建新站点页面中填写“网站名称”(Website Name)以及“网站类型”(Category)，然后点击“创建站点”(Create Site)。

   
   

3. 如果你愿意的话，选择一个付费订阅。 你也可以点击左侧的“安装Disqus”(Install Disqus)来跳过此步。

4. 下一步，选择Disqus的安装平台。 此处选择页面底部的“上面没有列出我使用的平台，使用通用代码安装” (I don’t see my platform listed, install manually with Universal Code)。

   
   

5. 点击页面底部的“配置”(Configure)按钮跳过“通用代码安装指南”(Universal Code install instructions)。

6. 在“配置Disqus”(Configure Disqus)页面中按需填写Disqus个性化配置。 然后，点击“完成安装”(Complete Setup)和“关闭配置”(Dismiss Setup)按钮来结束配置。

7. 下一步，在评论服务首页的右上角点击“编辑配置”(Edit Settings)按钮。

   
   

8. 在“为你的站点配置Disqus”(Configure Disqus for Your Site)页面上找到“Shortname”的值， 复制到主题配置的评论配置项中。 例如，下面截图中的“Shortname”为my-hexo-blog-1：

   
   

   对应的主题配置为：

   _config.icarus.yml

   comment:
       type: disqus
       shortname: my-hexo-blog-1

9. （可选）你可以在文章的front-matter中加入disqusId来为文章添加Disqus唯一标识。 这样，你可以在未来更改文章的位置而不会丢失所有评论。

   source/_posts/some-post.md

   title: 我的第一篇文章
   date: 2015-01-01 00:00:01
   disqusId: some-disqus-id
   ---
   # Hello world

DisqusJS

在Disqus服务访问受限的地区可使用DisqusJS作为替代。 关于DisqusJS的配置过程可参考https://github.com/SukkaW/DisqusJS。

安装指南在线预览

1. 登录Disqus并访问此链接。 点击“注册新应用”(Register new application)或者“注册应用”(registering an application)来创建新的Disqus应用。

   
   

2. 在下一页面中填写“应用名称”(Label)，“介绍”(Description)，以及“网站地址”(Website)。 然后点击“注册我的应用”(Register my application)。

   
   

3. 应用创建完毕后，进入应用的“设置”(Settings)界面，在“域名”(Domains)输入框中填入你Hexo站点的域名，例如ppoffice.github.io。 然后点击页面底部的“保存更改”(Save Changes)按钮。

   
   

4. 点击当前页面中的“详情”(Details)链接切换到当前应用的主页。 从“OAuth设置”(OAuth Settings)部分中复制“API Key”到相应的主题配置项中。

   例如，下面截图中的“API Key”：

   
   

   对应为下面的主题配置：

   _config.icarus.yml

   comment:
       type: disqusjs
       shortname: my-hexo-blog-1
       api_key: xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       api: https://disqus.skk.moe/disqus/     # 可选填
       admin: ppoffice                         # 可选填
       admin_label: Admin                      # 可选填
       nesting: 4                              # 可选填

5. 如要更多了解DisqusJS和它的配置，请访问SukkaW/DisqusJS文档或 hexo-component-inferno。

Giscus

利用 GitHub Discussions 实现的评论系统。

安装指南在线预览

1. 准备一个公开的 GitHub 仓库（Repository）。

2. 访问GitHub Apps - giscus并点击“安装”(Install)。

   
   

3. (可选)如果你的账号下有组织账号，在下一页中选择需要安装 giscus 的用户。

   
   

4. 在下一页面选择将 giscus 安装到“所有仓库”(All repositories)或是“选定的仓库”(Only select repositories)。 然后点击“安装”(Install)按钮。

   
   

5. 若安装成功，网页将跳转到 giscus 官网。 你可以阅读每个配置项的说明，并按需配置你的 giscus。

6. 完成配置后，转到页面上的“启用 giscus”(Enable giscus)并从 giscus 的 HTML 代码中复制属性值到主题配置的对应配置项中。

   
   

   例如下面的 giscus 代码：

   giscus 安装代码 >folded

   <script src="https://giscus.app/client.js"
         data-repo="usr/repo"
         data-repo-id="X_xxxxxxxxxx"
         data-category="Announcements"
         data-category-id="XXX_xxxxxxxxxxxxxxxx"
         data-mapping="pathname"
         data-strict="0"
         data-reactions-enabled="0"
         data-emit-metadata="0"
         data-input-position="top"
         data-theme="noborder_light"
         data-lang="zh-CN"
         data-loading="lazy"
         crossorigin="anonymous"
         async>
   </script>

   对应下面的主题配置：

   _config.icarus.yml

   comment:
       type: giscus
       repo: usr/repo                   # 必填项
       repoId: X_xxxxxxxxxx             # 必填项
       category: Announcements          # 可选填，默认为 Announcements
       categoryId: XXX_xxxxxxxxxxxxxxxx # 必填项
       mapping: pathname                # 可选填，默认为 pathname
       strict: false                    # 可选填
       reactionsEnabled: false          # 可选填
       emitMetadata: false              # 可选填
       inputPosition: top               # 可选填，默认为 top
       theme: noborder_light            # 可选填，默认为 noborder_light。页面为亮色时使用
       darkTheme: noborder_dark         # 可选填，默认为 noborder_dark。页面为暗色时使用
       lang: zh-CN                      # 可选填，默认为 en
       lazy: true                       # 可选填，默认为 false

7. 注意事项：

   • theme在页面为亮色时使用，darkTheme在页面为暗色时使用，即设置了appearance: dark，或者设置了appearance: auto且访客的系统使用暗色配色时。 如果你从 giscus 代码中复制data-theme，请把亮色主题填入theme，把暗色主题填入darkTheme。
   • 如要使用你自己的 giscus 主题，请将theme设置为custom，并将customThemeCss设置为该主题CSS文件的URL。 无论页面是亮色还是暗色，都会使用这个自定义主题，darkTheme会被忽略。
   • 如果mapping为specific或number，还需要将term设置为讨论的搜索词或编号，例如mapping: number搭配term: 1。 否则评论区的位置会显示一条提示，提醒你设置term。

Gitalk

Gitalk把评论保存在GitHub仓库的issue或discussion中。 访客通过GitHub应用(GitHub App)和你自己部署的Gitalk代理登录。

安装指南在线预览

1. 登录GitHub并点此创建一个新的GitHub应用。 如果要在组织下创建应用，请改为进入组织设置中的“开发者设置”(Developer settings)。 填写“应用名称”(GitHub App name)和“应用主页”(Homepage URL)。 “回调地址”(Callback URL)暂时留空，并取消勾选“Webhook”下的“启用”(Active)。 在“仓库权限”(Repository permissions)中，如果把评论保存在issue中，将“Issues”设为“读写”(Read and write)； 如果保存在discussion中，将“Discussions”设为“读写”(Read and write)。 然后，点击“创建GitHub应用”(Create GitHub App)按钮。

2. 在应用设置页面记下“App ID”和“Client ID”。 点击“生成新的client secret”(Generate a new client secret)和“生成私钥”(Generate a private key)来获取client secret和私钥。

3. 按照Gitalk代理部署指南将Gitalk代理部署到Cloudflare Workers或腾讯云开发(CloudBase)上。 把上一步得到的App ID、Client ID、client secret和私钥填入它的.env文件中。 将GITALK_ALLOWED_ORIGINS设为你Hexo站点的源地址，例如https://ppoffice.github.io。 记下部署完成后输出的代理地址，例如https://my-gitalk.octocat.workers.dev。

4. 回到应用设置页面。 将“回调地址”(Callback URL)设为代理地址加上/oauth/callback，例如https://my-gitalk.octocat.workers.dev/oauth/callback，然后保存更改。

5. 准备一个公开的GitHub仓库(Repository)用来保存评论。 如果把评论保存在discussion中，请在仓库设置中开启“Discussions”，并确保仓库至少有一个讨论分类。

6. 打开https://github.com/apps/<app-slug>/installations/new，其中<app-slug>是应用公开地址的最后一段。 选择“仅选定的仓库”(Only select repositories)，选中上一步的仓库，然后点击“安装”(Install)按钮。

7. 将Client ID和代理地址填入主题配置的相应配置项中。 例如，对于下面的Client ID和代理地址：

   GitHub应用和Gitalk代理

   Client ID
   Iv23lixxxxxxxxxxxxxx
   代理地址
   https://my-gitalk.octocat.workers.dev

   对应如下的主题配置：

   _config.icarus.yml

   comment:
       type: gitalk
       client_id: Iv23lixxxxxxxxxxxxxx
       proxy: https://my-gitalk.octocat.workers.dev
       repo: Some-of-Your-GitHub-Repo  # 仓库名称，不带所有者
       owner: you_github_name
       admin:
           - you_github_name
       backend: issues                 # 可选填，默认为issues。设为discussions时把评论保存在discussion中
       category: General               # 可选填。新建discussion时使用的讨论分类名称或slug
       per_page: 10                    # 可选填，默认为10。最大为100
       distraction_free_mode: false    # 可选填
       pager_direction: last           # 可选填，默认为last。可选last或first
       create_issue_manually: true     # 可选填，默认为true
       enable_hotkey: true             # 可选填，默认为true。按Cmd或Ctrl + Enter提交评论
       language: zh-CN                 # 可选填

8. 注意事项：

   • Gitalk会跟随页面的外观：设置appearance: dark时为暗色，设置appearance: auto时跟随访客系统的配色。
   • client secret和私钥只配置在代理上，不要填入主题配置。
   • 设置create_issue_manually: true时，管理员需要在每个页面上登录，并点击Gitalk显示的按钮来创建该页面的issue或discussion。
   • 如要让某个页面使用已有的issue或discussion，请在该页面的front-matter中把number设为它的编号。 由于front-matter会替换整个comment配置，请把其他评论配置项也一并复制过去。
   • 关于上述配置的含义和可选值，请参考Gitalk文档或 hexo-component-inferno。

Isso

如果你希望自己搭建一个评论系统而不是依赖第三方的评论服务时，Isso是一个可行的选择。 然而，不同于第三方评论系统，你需要准备一个Web服务器用来运行Isso服务端程序。

安装指南

1. 请参照Isso文档安装并启动Isso服务器。

2. 将Isso服务器的HTTP URL填入主题配置的相应配置项中。 例如，如果你的Isso服务地址为https://posativ.org/isso/api/，你会有如下的评论配置：

   _config.icarus.yml

   comment:
       type: isso
       url: posativ.org/isso/api

LiveRe

此评论插件可能会被部分广告拦截扩展拦截，请酌情使用。

安装指南在线预览

1. 登录LiveRe管理后台并添加你的站点。 填写站点的名称和地址，并验证你的邮箱。

2. 在LiveRe管理后台中复制站点的安装代码。

3. 复制代码中client-id的值到主题配置中的相应配置项中。 例如，下方的LiveRe代码：

   LiveRe安装代码

   <livere-comment client-id="AbCdEfGhIjKlMnOpQrSt"></livere-comment>
   <script type="module" src="https://www.livere.org/livere-widget.js"></script>

   对应的主题配置为：

   _config.icarus.yml

   comment:
       type: livere
       client_id: AbCdEfGhIjKlMnOpQrSt

   如果你使用的是旧版LiveRe City代码，请改为把uid设置为其中data-uid的值。

Twikoo

Twikoo是一个基于云函数的自建评论系统。 不同于其他第三方评论服务，在Icarus中设置和使用Twikoo之前，你需要将它的后端部署到云环境上。

安装指南在线预览

1. 按照Twikoo文档，将Twikoo云函数部署到你选择的云服务商上。 Icarus加载2.0.17版本的Twikoo客户端，请部署相同版本的Twikoo后端。

2. 将你部署的env_id填入主题配置的对应配置项中。 如果将Twikoo部署到腾讯云开发(CloudBase)，它是环境ID；如果部署到Vercel或自己搭建，它是你的部署地址，例如https://your-twikoo.vercel.app。

   _config.icarus.yml

   comment:
       type: twikoo
       env_id: xxxxxxxx         # 必填项。环境ID，或者你的部署地址
       region: ap-guangzhou     # 可选填。腾讯云开发的地域
       lang: zh-CN              # 可选填。默认为页面或站点的语言

utterances

安装指南在线预览

1. 准备一个公开的GitHub仓库(Repository)。

2. 访问GitHub Apps - utterances并点击“安装”(Install)。

   
   

3. (可选)如果你的账号下有组织账号，在下一页中选择需要安装utterances的用户。

   
   

4. 在下一页面选择将utterances安装到“所有仓库”(All repositories)或是“选定的仓库”(Only select repositories)。 然后点击“安装”(Install)按钮。

   
   

5. 若安装成功，网页将跳转到utterances官网。 你可以阅读每个配置项的说明，并按需配置你的utterances。

6. 完成配置后，转到页面上的“开启utterances”(Enable Utterances)并从utterances的HTML代码中复制属性值到主题配置的对应配置项中。

   
   

   例如下面的utterances代码：

   utterances安装代码 >folded

   <script src="https://utteranc.es/client.js"
         repo="Your-GitHub-Username/Your-Public-Repo-Name"
         issue-term="pathname"
         theme="github-light"
         crossorigin="anonymous"
         async>
   </script>

   对应下面的主题配置：

   _config.icarus.yml

   comment:
       type: utterances
       repo: Your-GitHub-Username/Your-Public-Repo-Name
       issue_term: pathname        # 必填项，与issue_number二选一填写
       # issue_number: 100         # 必填项，与issue_term二选一填写。将页面对应到你手动创建的GitHub issue
       label: some-issue-label     # 可选填
       theme: github-light         # 可选填，默认为github-light。页面为亮色时使用
       dark_theme: github-dark     # 可选填，默认为github-dark。页面为暗色时使用

7. 注意事项：

   • issue_term和issue_number必须且只能设置一个，两个都设置会导致配置检查失败。 如要按编号把每篇文章对应到各自的issue，请在文章的front-matter中设置issue_number，并把其他评论配置项一并写上，因为front-matter会替换整个comment配置。
   • theme在页面为亮色时使用，dark_theme在页面为暗色时使用，即设置了appearance: dark，或者设置了appearance: auto且访客的系统使用暗色配色时。 两者的取值都可以是github-light、github-dark、github-dark-orange、icy-dark、dark-blue或photon-dark。

Valine

安装指南在线预览

自hexo-component-inferno 4.2.0起，Valine已弃用，使用它生成网站时会输出警告。 Valine用来存储评论的LeanCloud将于2027年1月12日停止服务。 此外，任何人只要拿到你公开的App ID和App Key，就能读取Valine存储的评论：评论者的邮箱地址始终会暴露， 如果设置了record_ip: true，评论者的IP地址也会暴露 （ppoffice/hexo-theme-icarus#788）。 请换用Waline、Twikoo或其他评论系统。

1. 按照快速开始文档创建LeanCloud应用。

2. 将你LeanCloud应用的“App ID”和“App Key”复制到主题配置的对应配置项中。 此外，你可以参考配置项来了解可选配置项的详情和可能的配置值。 下面是示例配置：

   _config.icarus.yml

   comment:
       type: valine
       app_id: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
       app_key: xxxxxxxxxxxxxxxxxxxxxx
       placeholder: ""                 # 可选填
       avatar: mm                      # 可选填
       avatar_force: false             # 可选填
       meta: ["nick", "mail", "link"]  # 可选填
       page_size: 10                   # 可选填
       lang: zh-CN                     # 可选填
       visitor: false                  # 可选填
       highlight: true                 # 可选填
       record_ip: false                # 可选填
       server_urls:                    # 可选填
       emoji_cdn:                      # 可选填
       emoji_maps:                     # 可选填
       enable_qq: false                # 可选填
       required_fields: []             # 可选填

Waline

安装指南在线预览

1. 按照快速上手将Waline服务端部署到Vercel。 注意LeanCloud将于2027年1月12日停止服务（参见Valine），所以如果你现在开始使用Waline，请把评论存储在Waline支持的其他数据库中。

2. 将你Vercel项目的“服务器地址”(Server URL)复制到主题配置的对应配置项中。 通常它类似于https://your-domain.vercel.app。 此外，你可以参考前端配置来了解可选配置项的详情和可能的配置值。 下面是示例配置：

   _config.icarus.yml

   comment:
       type: waline
       server_url: https://your-domain.vercel.app
       path: window.location.pathname                # 可选填。类似/posts/hello/的路径，或者JavaScript表达式
       lang: zh-CN                                   # 可选填
       locale:                                       # 可选填
           placeholder: 'Comment here...'
       emoji:                                        # 可选填。设为false时关闭表情
           - '//unpkg.com/@waline/emojis@1.0.1/weibo'
       # dark: auto                                  # 可选填。不设置时跟随页面外观
       meta: ["nick", "mail", "link"]                # 可选填
       required_meta: []                             # 可选填
       login: enable                                 # 可选填
       word_limit: 0                                 # 可选填
       page_size: 10                                 # 可选填
       image_uploader: false                         # 可选填。设为true时关闭图片上传
       highlighter: false                            # 可选填。设为true时关闭代码高亮
       tex_renderer: false                           # 可选填。设为true时关闭TeX渲染
       search: false                                 # 可选填。设为true时关闭图片搜索
       pageview: false                               # 可选填。不要与waline_pageview插件同时开启
       comment: false                                # 可选填
       copyright: true                               # 可选填

   image_uploader、highlighter、tex_renderer和search这四个配置项用来关闭Waline的对应功能： 设为true时会关闭该功能（Icarus会把这个选项以false传给Waline），留空或设为false时则保持Waline对该功能的默认行为。 path可以是以/开头的固定路径，如/posts/hello/；其他值都会被当作JavaScript表达式，默认为window.location.pathname。

   不设置dark时，Waline会跟随页面的外观：设置appearance: dark时为暗色，设置appearance: auto时跟随访客系统的配色。 将dark设置为true、false、auto（跟随系统配色），或者一个CSS选择器（匹配到Waline的某个祖先元素时开启暗色模式），可以覆盖这一行为。

   pageview配置项会通过Waline评论统计并显示页面浏览量。 Icarus还提供了waline_pageview插件，它通过Waline服务端统计页面浏览量，并显示在文章头部（参见网站统计插件）。 两者只能开启一个：同时开启时每次浏览会被统计两次，生成网站时也会输出警告。

文章内容有误？请点击此处提交修改。