本地程序

目录

简介

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

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

公告

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

主要功能

安装

安装依赖

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

Linux / Mac 用户

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

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

Windows 用户

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

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

下载软件包

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

当前版本 0.2.12

解压软件包

这一步骤里的解压位置，即『本地程序』的安装位置，需保证浏览器有权限访问该位置。

mkdir -p ~/.local/apps
unzip ~/Downloads/maoxian-web-clipper-native-linux-chromium.zip -d ~/.local/apps/maoxian-web-clipper-native


unzip ~/Downloads/maoxian-web-clipper-native-linux-chromium.zip -d /Applications/maoxian-web-clipper-native

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

安装软件

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

进入你的『本地程序』文件夹里，然后：

这一步骤做的事情是：把『本地程序』的当前位置告知给浏览器。当 MaoXian 扩展需要和『本地程序』交互时，浏览器就可以找到『本地程序』的位置。所以安装过后，就不要移动，删除或重命名『本地程序』文件夹了。 如果你非要移动，或重命名『本地程序』文件夹，你需要再运行一遍安装脚本，告诉浏览器新的『本地程序』位置。

配置下载路径

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

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

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 版本是正确的（大于2.4.1），并且已经将其添加到环境变量里。并且配置文件 config.yaml 里面的存储路径是真实存在的路径，「本地程序」会和 MaoXian 对接成功。如果你仔细走完了上面的安装流程，还是无法对接上的话。 请检查日志文件：tmp/app.log (在安装目录下) 是否存在，若存在则可以使用任何文本编辑器打开它进行进一步排查。

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

情况A：可以找到日志文件

找到日志文件意味着：「本地程序」已经由浏览器启动，并产生日志。

如果在日志文件中，发现错误：”(./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 配置的路径，在你的系统中是不存在的。则你需要新建对应的文件夹或者配置一个存在的路径。修复完后，在 扩展设置 > 本地程序 页面上，点击『重新加载』按钮。

若遇到其他错误信息，请寻求帮助

情况B：找不到日志文件

请根据 扩展设置 > 本地程序 页面上的错误信息，对应下文进行排查。

Firefox （火狐）浏览器

错误信息：

ErrorMessage: NativeApp: DisconnectErr:No such native application maoxian_web_clipper_native

可能原因：

错误信息：

ErrorMessage: NativeApp: DisconnectErr:An unexpected error occurred

可能原因：

错误信息：

ErrorMessage: Unknown Error

可能原因：

错误信息：

ErrorMessage: LogErr, Permission denied @ rb_sysopen - /xxx/xxx/xxx/tmp/app.log

原因：

Chromium/Chrome （谷歌）浏览器

错误信息：

ErrorMessage: this.API.connectNative is not a function

原因：

错误信息：

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

可能原因：

错误信息：

ErrorMessage: NativeApp: DisconnectErr:Native host has exited.

可能原因：

错误信息：

ErrorMessage: LogErr, Permission denied @ rb_sysopen - /xxx/xxx/xxx/tmp/app.log

原因：

确定和解决浏览器找不到 ruby

1) ruby 安装不正确。

请确保当你运行 ruby -v 的时候，可以得到正确的 ruby 版本。如若不是，则重新安装即可。请确保 ruby 已经添加到环境变量里。

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

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

如何确认

可以通过从命令行启动浏览器的方式来确认，比如运行 /usr/bin/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。

确定是否「本地程序」路径有权限问题

0）先关闭浏览器。

1）找到浏览器的位置，比如在 Linux 上通过 whereis chromium。

2） 使用命令行的方式启动浏览器，如：运行命令 /usr/bin/chromium ，启动浏览器，再到 MaoXian 设置页面查看「本地程序」的状态，观察到错误后，查看命令行有没有相关错误信息。

如果有权限问题，一般可以观察到： Operation not permitted 或者 Permission denied 语句，如下面的 Chromium 的命令行输出：

shell-init: error retrieving current directory: getcwd: cannot access parent directories: Operation not permitted
ruby: Operation not permitted -- /Users/test/Downloads/maoxian-web-clipper-native/main.rb (LoadError)

一般为整个路径的某个目录权限不允许，则把本地程序复制到别的地方（参考解压软件包那一小节），即可修复。

寻求帮助？

首页