简介
这是一个很小的本地程序,我们开发这个程序增强 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
- Mac
- Windows
解压软件包
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 ,那麼請點擊這裏,查看如何對接。
查看状态并启用
请重启你的浏览器后,到 扩展设置页面 > 本地程序 小节查看当前状态。
- 请先查看『权限』那一小节,你需要授权一个权限,根据页面提示,如果还没有授权,则点击『授予权限』按钮进行授权。
- 授权成功后,查看『当前状态』那一小节,如果能看到 「本地程序」的版本号,则 MaoXian 扩展已经和 「本地程序」对接上了。如果显示的是错误信息,请查看下方 常见错误 小节,排查错误。
- 确保对接上后,请勾选下方的 启用该处理程序 。
在两者对接上,并且「本地程序」已启用后。就可以使用「本地程序」了,比如到 扩展设置页面 > 存储设置 选用「本地程序」来下载裁剪结果。
注: 如果你需要在浏览器上预览你裁剪下来的文件, 我们强烈建议你 允许 MaoXian 访问本地网址,以便可以方便地查看裁剪下来的文件。
卸载软件
Linux 或 Mac 直接运行 ./uninstall.sh
脚本,再删除掉整个程序目录。
在 Windows 上,直接双击 uninstall.bat
,再删除掉整个程序目录。
更新软件
- 先备份 Native App 目录下的
config.yaml
(复制到别的地方) - 卸载 Native App
- 在本页面下载最新版本,再解压软件包
- 用你备份的
config.yaml
覆盖解压出来的文件夹的 config.yaml. - 安装新的程序
运用最新的配置
有些用户更改了 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 里面的内容。