常見問題與疑難排解

「以前在舊筆電上好好的，換了新電腦後 protect/run 就失敗了」

預設情況下，加密產物會鎖定在建立它的那台機器上——換到新機器並不會一併帶走這個鎖定。啟用新機器（下一次執行 protect/build 時會自動完成），然後在新機器上重新加密。如果你需要讓同一份產物在多台你事先無法掌控的機器上執行，請改用便攜產物——見加密程式碼。

「在產生產物的同一台機器上卻拋出 VaultLockedError」

原因不外乎兩種：這台機器的身分變化大到看起來像是另一台裝置了（例如大規模重灌系統，或某些虛擬化／複製情境），或是本地保管庫檔案被移動或遭竄改過。至於為什麼 MagicLock 不會告訴你究竟是哪一種，見安全模型。重新執行 magiclock activate 以重新設定這台機器即可。

「不安裝 SDK 也能執行 .pya 嗎？」

執行它需要安裝 magiclock（magiclock run app.pya）——但僅此而已，不需要帳號、不需要登入、不需要連網。執行你所交付應用程式的人，只需要安裝這個套件，不需要在你這邊擁有帳號。

「Python 3.12 加密出的 .pya 在 3.13 上打不開」

這是預期行為——見 API 參考裡的相容性說明。請在新的直譯器版本上重新執行 protect/build，而不要讓同一個產物跨 Python 版本使用。

「訂閱到期後，已經交付出去的應用程式會怎樣？」

新的加密會失敗，直到你續訂為止——magiclock protect/build 會回報訂閱相關的錯誤。但你已經產生並交付出去的產物，仍會照常解密、照常執行；解密永遠不會檢查你的訂閱狀態。見帳號與啟用。

「如何停用一台遺失或已退役的機器？」

magiclock deactivate   # run on the machine itself, or via the account portal

這會釋出這台機器的席位，並阻止它繼續在你帳號名下加密任何新內容。它不會回頭影響這台機器先前已經產生的產物——原因見帳號與啟用。

「CI 回報 NotLoggedInError / NotActivatedError」

無人值守的執行環境無法走互動式瀏覽器登入。從你的帳號入口網站鑄造一組權杖，並以非互動方式傳入：

export MAGICLOCK_TOKEN=<token-from-your-account-portal>
magiclock protect app.py

見帳號與啟用。

「protect/build 在完全沒有網路的情況下失敗」

從你最近一次成功核實算起，會有 12 小時的寬限窗口，超過這個窗口才會阻擋加密——見帳號與啟用裡的表格。如果你從未成功連線啟用過，就沒有寬限可用；先成功連線一次以建立寬限。

仍未解決？

在失敗的指令後面加上 --help，即可查看完整可用旗標（例如 magiclock protect --help），或透過你帳號入口網站的支援管道與我們聯絡。