第一部・認識爾雅 ／ 1.2

安裝與啟動

七種平台各該下載哪一個檔、解開之後放到哪裡、怎麼從原始碼裝，以及命令列上那幾個選項與環境變數各自管什麼。

閱讀時間 約 10 分鐘 對象 第一次安裝的人 先備知識 無 版本 v1.0 ・ 2026-08-26
1.2.1

兩種安裝方式

下載現成的執行檔，或用 Rust 自己編。

① 下載 Release（建議）

從 GitHub Releases 抓對應平台的壓縮檔，解開就是一個執行檔，不用裝任何東西。

  • 七種平台都有現成檔
  • 附 SHA-256 可以驗
  • 要自己放進 PATH

② 從原始碼安裝

有 Rust 環境的話，cargo install 一行就好，之後也方便跟著更新。

  • 需要 Rust 1.85 或更新版本
  • 裝到 Cargo 的 bin 目錄，通常已經在 PATH 裡
  • 第一次編譯要等幾分鐘
爾雅只有一個執行檔

沒有安裝程式、沒有服務、不寫登錄檔，也不會在系統裡散落設定。它唯一會主動讀的設定檔是按鍵配置（見 4.1.7），而且沒有也能跑；唯一會主動寫的檔案是你按下儲存的文件，以及你自己叫它存的常用語與巨集 JSON（見 2.4.5）。要移除就是把執行檔刪掉。

1.2.2

下載對應平台的壓縮檔

先確認自己是哪一種 CPU，再挑檔名。

到 github.com/walisayu/erya/releases/latest 挑一個 .tar.gz：

系統架構Release target（檔名裡的字串）
LinuxIntel／AMD 64-bitx86_64-unknown-linux-gnu
Linux／Raspberry Pi OS 64-bitARM64aarch64-unknown-linux-gnu
Raspberry Pi OS 32-bitARMv7 hard-floatarmv7-unknown-linux-gnueabihf
macOSIntelx86_64-apple-darwin
macOSApple Silicon（M 系列）aarch64-apple-darwin
WindowsIntel／AMD 64-bitx86_64-pc-windows-msvc
WindowsARM64aarch64-pc-windows-msvc

不確定自己是哪一種

  • macOS：終端機打 uname -m，arm64 就是 Apple Silicon，x86_64 就是 Intel。
  • Linux／樹莓派：一樣是 uname -m。aarch64 選 ARM64，armv7l 選 ARMv7，x86_64 選 Intel／AMD。
  • Windows：設定 →「系統」→「系統資訊」看「系統類型」。
樹莓派要看的是作業系統，不是硬體

Raspberry Pi 4／5 的 CPU 是 64 位元，但 Raspberry Pi OS 有 32 位元版本。系統是 32 位元就得選 ARMv7，選了 ARM64 會跑不起來。用 uname -m 看到的是系統實際位元數，最準。

1.2.3

驗證檔案與放進 PATH

解壓縮之後只有一個檔：erya（Windows 是 erya.exe）。

每個壓縮檔都附一個同名的 .sha256，Release 頁面上也有整包的 SHA256SUMS。想確認下載沒壞（或沒被動過手腳）：

系統指令
macOSshasum -a 256 erya-*.tar.gz
Linuxsha256sum -c erya-*.tar.gz.sha256
Windowscertutil -hashfile erya-*.tar.gz SHA256

算出來的字串要跟 .sha256 檔裡的一致。接著把執行檔放到 PATH 內的任何一個目錄：

系統常用位置
macOS／Linux（只給自己用）~/.local/bin　或　~/bin
macOS／Linux（全機共用）/usr/local/bin（需要 sudo）
Windows自己建一個 C:\Tools，再把它加進「環境變數 → Path」
macOS 第一次執行會被擋

從網路下載的執行檔帶有隔離屬性，macOS 會說「無法打開，因為無法驗證開發者」。解法是把屬性清掉：

xattr -d com.apple.quarantine ~/.local/bin/erya

或是在「系統設定 →『隱私權與安全性』」裡按一次「仍要打開」。這是 macOS 對所有未經 App Store 簽章的程式一視同仁的行為，不是爾雅特有的。

1.2.4

從原始碼安裝

需要 Rust 1.85 或更新版本。

先確認 Rust 版本夠新（rustc --version），沒有的話用 rustup 裝。接著在專案目錄裡：

指令做什麼
cargo run --release -- [檔案]編譯並直接跑一次，不安裝。-- 後面的東西才會傳給爾雅。
cargo install --path .編譯並把 erya 裝到 Cargo 的 bin 目錄（通常是 ~/.cargo/bin）。
erya [檔案]裝好之後就這樣用。
別忘了那個 --

cargo run --release 檔案.txt 會被 Cargo 當成自己的參數而出錯。要開檔案一定得寫成 cargo run --release -- 檔案.txt，兩個減號告訴 Cargo：後面的東西是給程式的，不是給我的。

1.2.5

啟動：帶檔名或不帶

後面可以接零個、一個或多個檔案。

指令結果
erya開一個空白的未命名文件。第一次儲存時會問檔名。
erya 報告.txt開這個檔。檔案不存在也不會報錯，會開一個空白文件，第一次儲存時才真的建立檔案。
erya a.txt b.txt c.txt一次開三個頁籤，停在第一個。
erya -- -奇怪的檔名.txt-- 之後的東西一律當檔名，不會被當成選項。
erya 某個目錄會失敗並印出「某個目錄 是目錄，不是文字檔」。爾雅不接受用目錄當參數，要瀏覽目錄請進去之後按 Ctrl+O（見 2.1.2）。
檔案是符號連結的話

爾雅會先把符號連結解析成真正的目標路徑再開，儲存時也是寫回目標檔，不會把連結本身換成一般檔案。用 erya ~/.zshrc 這種常常是連結的路徑時，行為會跟你預期的一樣。

1.2.6

命令列選項

五個，全部都是「印個東西就結束」或「換一份設定」。

選項做什麼
-h, --help印出說明後結束。內容包含用法、選項、環境變數與常用按鍵，而且會照你的介面語言顯示。
-V, --version印出版本後結束，例如 erya 1.0.0。
--languages列出翻譯目錄裡實際找得到的語言，一行一個，格式是「代碼Tab名稱」。
--keymap <檔案>這一次執行改用指定的按鍵配置檔（見 4.1.5）。後面沒接路徑會直接失敗。
--print-default-keymap把完整的預設按鍵配置印到標準輸出，通常拿來重導成自己的設定檔起點。

常見用法：

  • erya --print-default-keymap > keymap.toml — 產生一份含全部動作名稱的起始設定檔。
  • erya --keymap keymap.toml 報告.txt — 用改好的設定檔開檔。
  • erya --languages — 確認 ERYA_LANG 該填什麼代碼。
不認得的選項會直接讓程式結束

任何以 - 開頭又不在上表裡的參數，都會得到「erya: 不支援的選項：-x」並以失敗狀態結束，不會忽略它繼續開檔。檔名剛好以減號開頭時，記得先寫 --。

1.2.7

四個環境變數

全部都是選用的；一個都不設也能跑。

變數管什麼詳見
ERYA_LANG介面語言代碼，例如 zh-TW、zh-CN、en、ja。沒設時依序看 LC_ALL、LC_MESSAGES、LANG。4.2.4
ERYA_LOCALES_DIR翻譯檔目錄，預設是 locales/。想放自己翻的語言就指到那裡。4.2.5
ERYA_KEYMAP按鍵配置檔路徑，等同於每次都加 --keymap。4.1.7
ERYA_KEYMAPS_DIR系統設定（F2）那一頁列出的配置要從哪個目錄讀，預設是 keymap/。4.1.3

臨時用一次就寫在指令前面：

  • ERYA_LANG=en erya 報告.txt — 這一次用英文介面。
  • ERYA_KEYMAP=~/my.toml erya — 這一次用自己的按鍵配置。

想長期生效就寫進 ~/.zshrc、~/.bashrc（Windows 則寫進使用者環境變數）。

1.2.8

終端機需要滿足的條件

兩個硬條件：要是真的終端機，而且不能太小。

  1. 必須是互動式終端機。標準輸入與標準輸出兩邊都要是 TTY。把爾雅接到管線或重導向會直接失敗並顯示「爾雅 Erya 必須在互動式 Terminal 中執行」。cat a.txt | erya、erya > out.txt 這種寫法都不行——它是編輯器，不是過濾器。
  2. 視窗至少要 24 欄 × 6 列。比這個小的話，畫面會整片換成一行黃字「終端視窗太小，請放大後繼續」，放大之後自動恢復，不會弄丟你正在編輯的內容。實務上請給它 80 × 24 以上；十六進位檢視要顯示每列 32 位元組還需要 144 欄（見 3.3.3）。
  3. 建議支援 bracketed paste。現在的終端機幾乎都支援。有它的話，貼上大段文字會被當成一次貼上，而不是被當成一連串按鍵處理。爾雅會在啟動時開啟、離開時關掉。
離開之後畫面會還原

爾雅用的是終端機的「替代畫面」，離開時會把你原本的畫面、游標與各種模式一併還原，不會在捲動紀錄裡留下一整片編輯畫面。就算是異常結束，還原程序也會跑。

1.2.9

啟動不了的時候

照訊息對號入座；完整的疑難排解在 4.3。

看到的訊息原因與處理
command not found: erya執行檔沒放進 PATH。先用完整路徑試 ~/.local/bin/erya，能跑就是 PATH 的問題（1.2.3）。
Permission denied執行權限沒開。chmod +x erya。
macOS：無法驗證開發者隔離屬性。xattr -d com.apple.quarantine erya（1.2.3）。
cannot execute binary file下載到不同架構的版本。用 uname -m 重新確認（1.2.2）。
必須在互動式 Terminal 中執行用了管線或重導向。直接在終端機裡執行（1.2.8）。
終端視窗太小視窗小於 24×6。放大就好（1.2.8）。
不支援的選項：…打錯選項，或檔名以減號開頭。加 --（1.2.6）。
… 是目錄，不是文字檔參數給了目錄。改給檔案，或先開爾雅再按 Ctrl+O（1.2.5）。
無法載入按鍵設定，已使用預設值：…這不是錯誤，程式照跑。設定檔有語法問題或按鍵衝突，爾雅退回完整預設值並在訊息列說明原因（4.1.8）。