本地程序

简介

这是一个很小的本地程序，我们开发这个程序增强 Maoxian 的能力。

注意： 如果你只是为了修改 MaoXian 的默认下载目录，则完全没有必要安装『本地程序』，请查看这里查看如何修改默认下载位置。

公告

ruby 的最新版本（2.7.0）对之前的接口有一些不兼容，这会导致裁剪网页的时候，图片无法下载成功。如果你安装的 ruby 是 2.7.0 以上，则需要安装 0.2.3 以上的「本地程序」才能正常使用。

主要功能

• 默认
  • 下载文件 （用于绕过浏览器的下载功能，从而避免与下载管理软件发生冲突）
  • 删除裁剪信息 （让我们可以删除裁剪历史的同时，删除其对应的文件）
  • 刷新裁剪历史 （当你有两个裁剪源（比如：一台电脑上的两个浏览器或两台电脑上的浏览器）并且想让浏览器上的裁剪历史保持最新的时候，这一项非常有用。）
• Vnote
  • 以 Vnote 的存储格式，存储裁剪下来的 Markdown 文件。当你对接上 Vnote 后，就可以在 Vnote 上管理你裁剪下来的文件。详情请看这里

安装

安装依赖

该软件依赖于 Ruby， 所以我们要先安装 Ruby，请安装 2.4.1 以上版本。

Linux / Mac 用户

很可能系统就自带了 ruby，请用命令 ruby -v 查看。罗嗦一句，如果你是命令行新手，不知道如何运行命令。没关系，每个人都是从新手过来的，不要看到命令行就害怕。请利用搜索引擎学习如何运行命令（比如：搜索 Mac 系统如何运行命令），再走下面的流程。

如果输出的是 ruby 的版本信息，则说明你的系统已经安装了 ruby, 否则请到 ruby 官网 进行安装

Windows 用户

请到 这里 下载安装包，提醒一下，这里直接下载 WITHOUT DEVKIT 下面的版本即可。安装的时候确保勾选上

• 把 ruby 添加到环境变量（该项必须勾选，否则「本地程序」无法正常启动）。
• 使用 UTF-8 作为外部编码 （强烈建议你勾选该项，这样你在跨系统同步文件时候，才不会发生乱码问题）。

最好在安装成功后，验证一下。通过 Win+R 调出运行窗口 > 输入 cmd 回车 > 输入 ruby -v 回车 。如果输出的是 ruby 的版本信息，则说明 ruby 安装成功，并且已经添加到环境变量。

下载软件包

请根据你的系统信息和浏览器类型， 下载对应的软件包

当前版本 0.2.11

• Linux
  • native-app-chrome.zip
  • native-app-chromium.zip
  • native-app-firefox.zip
• Mac
  • native-app-chrome.zip
  • native-app-chromium.zip
  • native-app-firefox.zip
• Windows
  • native-app-chrome.zip
  • native-app-chromium.zip
  • native-app-firefox.zip

解压软件包

Linux 或者 Mac

unzip maoxian-web-clipper-native-linux-chrome.zip -d maoxian-web-clipper-native

Windows

额，使用任何你喜欢的解压软件，把它解压到某个文件夹（由于是直接打包的文件，没有打包根文件夹）, :D

安装软件

注: 如果你的浏览器是基于 Chromium 或 Firefox 开发的浏览器，请使用这里的安装教程。

• Linux 或 Mac 直接运行 ./install.sh 进行安装
• 在 Windows 上，直接双击 install.bat （注意：你点击后，会发现有个命令窗口跳出来，程序会进行安装，安装完成后会显示：”press any key to continue” 则直接按下 Enter 就好了。 ）

配置下载路径

在开始使用之前，我们需要先配置，下载路径，也就是裁剪下来的文件存储的目录（等同于浏览器的下载目录）

编辑 config.yaml ， （随便用一个文本编辑器就可编辑）

config.yaml 这个文件必须是 UTF-8 的编码格式。 如果你是在 Windows 上的话，别用记事本打开，找一个能正确处理换行符的编辑器（比如 notepad++）。并且确保你保存的编码格式为 UTF-8 （有的编辑器在 Windows 上的默认编码格式不是 UTF-8，这点需要注意）。

注意： 配置的下载路径必须真实存在，否则程序会运行启动失败

Linux / Mac 例子

# config.yaml
environment: 'production'
data_dir: '/home/jack/clippings'
# avariable handler: 'default', 'vnote_v1'
msg_handler: 'default'

windows 例子

# config.yaml
environment: 'production'
data_dir: 'e:\jack\clippings'
msg_handler: 'default'

注意上方的 msg_handler 目前支持兩個值 default 和 vnote_v1 。如果你要對接 Vnote ，那麼請點擊這裏，查看如何對接。

查看状态并启用

请重启你的浏览器后，到 扩展设置页面 > 本地程序 小节查看当前状态。

1. 请先查看『权限』那一小节，你需要授权一个权限，根据页面提示，如果还没有授权，则点击『授予权限』按钮进行授权。
2. 授权成功后，查看『当前状态』那一小节，如果能看到 「本地程序」的版本号，则 MaoXian 扩展已经和 「本地程序」对接上了。如果显示的是错误信息，请查看下方 常见错误 小节，排查错误。
3. 确保对接上后，请勾选下方的 启用该处理程序 。

在两者对接上，并且「本地程序」已启用后。就可以使用「本地程序」了，比如到 扩展设置页面 > 存储设置 选用「本地程序」来下载裁剪结果。

注： 如果你需要在浏览器上预览你裁剪下来的文件， 我们强烈建议你 允许 MaoXian 访问本地网址，以便可以方便地查看裁剪下来的文件。

卸载软件

Linux 或 Mac 直接运行 ./uninstall.sh 脚本，再删除掉整个程序目录。

在 Windows 上，直接双击 uninstall.bat，再删除掉整个程序目录。

更新软件

1. 先备份 Native App 目录下的 config.yaml (复制到别的地方)
2. 卸载 Native App
3. 在本页面下载最新版本，再解压软件包
4. 用你备份的 config.yaml 覆盖解压出来的文件夹的 config.yaml.
5. 安装新的程序

运用最新的配置

有些用户更改了 config.yaml 里的配置，却发现扩展并没有马上应用最新的配置信息。这是属于正常现象，因为『本地程序』只在浏览器启动它时，才会去读取配置。你可以到 设置页面 > 本地程序 那里，点击『重新加载』按钮来加载最新的配置。你也可以通过重启浏览器的方法加载最新配置。

常见问题

一般情况下，当你的 ruby 版本是正确的，并且配置文件 config.yaml 里面的存储路径是真实存在的路径，「本地程序」会和 MaoXian 对接成功。如果你仔细走完了上面的安装流程，还是无法对接上的话。 请检查日志文件：tmp/app.log (在安装目录下)，使用任何文本编辑器打开即可。

在进行下面检查之前，你得确保你至少到过 扩展设置页面 > 本地程序 页面查看过状态信息，并且其显示的是某个错误信息。

注： 当你做出修改之后，请点击扩展上的 『重新加载』按钮，该按钮会重连本地程序。

浏览器无法连接『本地程序』

如果你在设置页面可以如下错误信息，则表明浏览器无法连接『本地程序』，这种情况下，是不会有日志生成的。

ErrorMessage: NativeApp: DisconnectErr:Specified native messaging host not found

或

ErrorMessage: NativeApp: DisconnectErr:No such native application maoxian_web_clipper_native

可能原因为：

基于 Chromium 或 Firefox 开发的浏览器，没有对一些目录做兼容。{#cannot-connect-other-browsers}

请查看基于Chromium 或 Firefox 开发的浏览器如何安装『本地程序』

浏览器找不到 ruby

在 Firefox 上表现为：

ErrorMessage: Unknown Error

1) ruby 安装不正确。

请确保当你运行 ruby -v 的时候，可以得到正确的 ruby 版本。如若不是，则重新安装即可。

2) 虽然 ruby 安装成功，但是浏览器无法找到它。

这种情况一般发生在 Mac 或 Linux 用户身上，如果你采用的是源码安装的方式，你可能会碰到此问题。

如何确认

可以通过从命令行启动浏览器的方式来确认，比如运行 chromium-browser 命令，然后再到 扩展设置页面 > 本地程序 页面，再查看命令行的输出，可以看到类似 “/usr/bin/env: ‘ruby’: No such file or directory” 这样的错误信息。

如何解决

把 main.rb (安装目录下) 第一行的 “/usr/bin/env ruby” 改成 ruby 的绝对路径，比如 “/home/jack/ruby-2.5.0/bin/ruby”。 或者是创建一个软链接到 /usr/bin 目录下，比如： ln -s /home/jack/ruby-2.5.0/bin/ruby /usr/bin/ruby。

浏览器与本地程序的连接已断开

置页面的错误信息：

NativeApp: DisconnectErr:Error when communicating with the native messaging host.

这个错误指的是由于未知的错误，浏览器断开了和「本地程序」的连接。这个说明浏览器已经可以找到「本地程序」，并且可以连接上，此时请查看日志文件 tmp/app.log 找到导致连接断开的错误信息，再参照下一小节找到解决方法。

配置文件的问题

如果在日志文件中，发现错误：”(./config.yaml): invalid trailing UTF-8 octet at line xxx column xxx”，则表示你的配置文件的编码格式不是 UTF-8 ，则重新把配置文件 config.yaml 另存为 UTF-8 编码格式，即可修复。

如果在日志文件中，发现错误： “Config Invalid, data_dir not exist: xxxxx” ，则表示你配置文件 config.yaml 里面的 data_dir 配置的路径，在你的系统中是不存在的。则重新配置即可。

还是不行？

可能发生 Bug 了。你可以用 ruby -v 检查下 ruby 版本， 若版本比 2.4.1 低，则重新安装更高的版本，重启浏览器，再试一下，还是不行的话，请到 项目 issue 页，给开发者提个issue, 并在 issue 里粘贴上 app.log 里面的内容。

---

首页