@willh/now

now

now 是一個 Rust CLI，用來把靜態網站交給既有 provider CLI 部署。

它不嘗試重寫 Firebase、Azure 或 FTP 的部署流程；它負責選擇可發布目錄、讀取非祕密設定、組合 provider CLI 命令，並在部署後輸出預設 URL。

---

支援平台

平台	Release asset
macOS Apple Silicon	now-aarch64-apple-darwin.tar.xz
macOS Intel	now-x86_64-apple-darwin.tar.xz
Linux x64 glibc	now-x86_64-unknown-linux-gnu.tar.xz
Windows x64	now-x86_64-pc-windows-msvc.zip

初版不支援 Linux arm64 與 musl。

每個 archive 旁邊都會有同名 .sha256 檔案。

---

安裝

npm

npm install -g @willh/now

npm 套件只包含 JavaScript wrapper 與安裝邏輯。安裝時會從 GitHub Release 下載目前平台的原生 binary，並驗證 SHA-256 checksum。

Unix-like

curl -fsSL https://raw.githubusercontent.com/doggy8088/now/main/install.sh | sh

預設安裝到 $HOME/.local/bin。可用 NOW_INSTALL_DIR 覆寫：

NOW_INSTALL_DIR=/usr/local/bin sh install.sh

Windows PowerShell

iwr https://raw.githubusercontent.com/doggy8088/now/main/install.ps1 -OutFile install.ps1
.\install.ps1

預設安裝到 $env:LOCALAPPDATA\now\bin。可用 -InstallDir 覆寫：

.\install.ps1 -InstallDir "$env:USERPROFILE\bin"

手動下載

1. 到 https://github.com/doggy8088/now/releases/latest 下載符合平台的 archive。
2. 下載同名 .sha256。
3. 驗證 checksum。
4. 解壓縮後把 now 或 now.exe 放進 PATH 內的目錄。

---

快速開始

now
now deploy
now deploy dist

now [path] 等同 now deploy [path]。

第一次在互動式終端機執行 now 或 now deploy，且尚未設定 provider 時，CLI 會啟動首次設定流程，協助選擇 provider 並把非祕密設定寫入 .now.json。非互動式環境或 --json 模式不會啟動提示流程，會直接輸出缺少 provider 的錯誤。

首次設定時若有明確指定 path，now 會先驗證該目錄，再把它保存為 .now.json 的 source。專案內目錄保存為相對於目前工作目錄的路徑，後續可直接執行 now 重複部署；專案外目錄保存為絕對路徑。

也可以明確啟動互動式設定精靈：

now init

now init 只會設定 provider 與相關選項，不會執行發布。若設定檔已存在，CLI 會先詢問是否重新設定並覆寫；拒絕時會保留原檔，接受時則以既有值作為提示預設值。

若只需修改單一設定，也可以使用：

now config set provider firebase-hosting

---

設定檔

now 讀取兩種設定檔：

類型	路徑
本機設定	.now.json
全域設定	~/.config/now/settings.json

合併優先序如下：

1. CLI flags
2. .now.json
3. ~/.config/now/settings.json

設定檔只保存非祕密設定。Azure Storage Blob 的 SAS URL 含有上傳權杖，不寫入 .now.json；.now.json 只保存 azure_blob.sas_url_env。

完整範例：

{
  "provider": "firebase-hosting",
  "source": null,
  "move_publishable_files_to_public": null,
  "base_url": "https://example.web.app",
  "default_url": null,
  "firebase": {
    "project": "my-firebase-project",
    "site": null
  },
  "azure_blob": {
    "sas_url_env": "NOW_AZURE_BLOB_SAS_URL"
  },
  "azure_swa": {
    "app_name": null,
    "environment": "production",
    "deployment_token_env": "SWA_CLI_DEPLOYMENT_TOKEN"
  },
  "ftp": {
    "host": "ftp.example.com",
    "remote_dir": "/public_html",
    "username_env": "NOW_FTP_USERNAME",
    "password_env": "NOW_FTP_PASSWORD"
  }
}

常用設定命令：

now init
now init --global
now config set provider firebase-hosting
now config set firebase.project my-project
now config get
now config get provider
now config doctor

---

Provider

Firebase Hosting

需求：

npm install -g firebase-tools
firebase login

建議設定：

now config set provider firebase-hosting
now config set firebase.project my-project
now config set base_url https://my-project.web.app

部署時會呼叫：

firebase deploy --only hosting

若設定 firebase.site，會改用 hosting:<site>。

為了相容舊設定，firebase 仍可被讀取；新設定建議使用 firebase-hosting。

Azure Storage Blob

Azure Storage Blob provider 不需要 Azure CLI。只要透過環境變數提供 container SAS URL，now 會直接使用 Azure Blob REST API 上傳檔案。

首次設定選擇 Azure Storage Blob 時，會要求輸入 SAS URL，但只會把 SAS URL 寫入 .env，.now.json 只保存環境變數名稱。

建議設定：

now config set provider azure-storage-blob
now config set azure_blob.sas_url 'https://mystorageaccount.blob.core.windows.net/$web?sv=...'

上述 azure_blob.sas_url 是便利設定入口：now 會自動把實際 SAS URL 寫入 .env 的 NOW_AZURE_BLOB_SAS_URL，並在 .now.json 寫入：

{
  "azure_blob": {
    "sas_url_env": "NOW_AZURE_BLOB_SAS_URL"
  }
}

若要自行管理環境變數，也可以直接設定：

export NOW_AZURE_BLOB_SAS_URL='https://mystorageaccount.blob.core.windows.net/$web?sv=...'
now config set azure_blob.sas_url_env NOW_AZURE_BLOB_SAS_URL

為了相容舊設定，azure-blob 仍可被讀取；新設定建議使用 azure-storage-blob。

SAS URL 必須指向 container，例如 Azure Static Website 常用的 $web container，且需要具備建立或寫入 blob 的權限。部署時會對每個檔案呼叫 Azure Blob Put Blob API，並使用 x-ms-blob-type: BlockBlob。

PUT https://mystorageaccount.blob.core.windows.net/$web/<file>?<sas-query>

若未設定 base_url 與 default_url，now 會從 sas_url_env 指向的 SAS URL 移除 query string，再加上預設頁面檔名來推導 Default URL。

Azure Static Web App

需求：

npm install -g @azure/static-web-apps-cli

首次設定選擇 Azure Static Web App 時，會要求輸入 deployment token。實際權杖只會寫入 .env，.now.json 只保存環境變數名稱。部署時會優先讀取程序環境變數，未設定時再讀取專案的 .env。

也可以自行把 deployment token 放在環境變數：

export SWA_CLI_DEPLOYMENT_TOKEN=...
now config set provider azure-static-web-app
now config set azure_swa.environment production
now config set azure_swa.deployment_token_env SWA_CLI_DEPLOYMENT_TOKEN

部署時會呼叫：

swa deploy <source> --env production

為了相容舊設定，azure-swa 仍可被讀取；新設定建議使用 azure-static-web-app。

Any Website (FTP)

需求：

lftp --version

帳號密碼請使用環境變數：

export NOW_FTP_USERNAME=deploy-user
export NOW_FTP_PASSWORD=...
now config set provider any-website-ftp
now config set ftp.host ftp.example.com
now config set ftp.remote_dir /public_html

部署時會用 lftp mirror -R --only-newer 上傳。初版不做遠端刪除同步。

為了相容舊設定，ftp 仍可被讀取；新設定建議使用 any-website-ftp。

---

來源目錄規則

未指定 path 時，now 會依序尋找：

1. dist/
2. build/
3. public/

若三者都不存在：

1. 互動式終端機會詢問是否把目前目錄的可發布檔案移到 public/。
2. 回答會寫入 .now.json 的 move_publishable_files_to_public，後續直接套用，不再重複詢問。
3. 若拒絕或處於非互動式環境且尚無記憶選擇，會部署目前目錄。
4. 部署目前目錄或移動檔案時，會排除 .now.json、.env、.env.*、.git/、node_modules/、target/ 與暫存檔。

若要清除記憶並讓 CLI 下次重新詢問：

now config set move_publishable_files_to_public null

指定 path 時會直接使用該目錄：

now deploy dist
now ./public

命令列 path 的優先序高於設定檔中的 source。除首次設定會保存明確指定的 path 外，後續指定 path 只覆寫當次部署來源，不會暗中改寫 .now.json；如需永久變更，請使用：

now config set source reports/example

也可以使用具名旗標，單次覆寫 .now.json 內的部署參數：

now --source dist
now deploy --source dist
now deploy --prefix releases/2026-07-18
now deploy --remote_dir /public_html/releases/2026-07-18

--source 覆寫 source，--prefix 覆寫 azure_blob.prefix，--remote_dir 覆寫 ftp.remote_dir。這些值只套用於當次部署，不會改寫 .now.json。--remote-dir 也可作為 --remote_dir 的別名。

---

URL 選擇規則

部署後輸出的 URL 依序選擇：

1. .now.json 或全域設定中的 default_url
2. index.html 搭配 base_url 或 provider 可推導的公開 URL
3. index.htm 搭配 base_url 或 provider 可推導的公開 URL
4. 根目錄唯一的 .html 或 .htm 頁面，搭配 base_url 或 provider 可推導的公開 URL
5. provider base URL 或 provider 可推導的公開 URL

畫面會以 Default URL: <url> 顯示判斷結果。若 base_url 與 default_url 都是 null，now 會盡量從 provider 設定推導完整 URL；目前 Azure Storage Blob 會從 sas_url_env 指向的 SAS URL 推導。若無法推導，檔案規則會輸出相對頁面名稱，例如 index.html。

---

常用命令

now --help
now
now public
now deploy
now deploy dist --provider firebase-hosting
now deploy --dry-run
now deploy --dry-run --json
now config get --global
now config doctor

詳細記錄

部署時加入 --verbose 可顯示設定檔位置、provider、來源目錄判斷、準備後的部署目錄、外部命令工作目錄、完整命令與參數、環境變數映射名稱、外部命令輸出及結束狀態：

now --verbose
now deploy --verbose
now deploy dist --verbose

詳細記錄會輸出到 stderr，因此可與 --json 同時使用而不破壞 stdout 的 JSON。權杖、密碼與 SAS URL query 不會顯示。

--verbose 也會開啟 provider 自身的偵錯模式：

Provider	偵錯設定
Firebase Hosting	firebase --debug
Azure Static Web App	swa --verbose silly
Any Website via FTP	lftp -d
Azure Storage Blob	顯示每個檔案的遮罩後目標 URL、大小與完成狀態

---

安全性

不要把 token、password、secret、account key 或 Azure Storage Blob SAS URL 寫入 .now.json。

建議做法：

類型	建議
Firebase Hosting	使用 firebase login 的既有登入狀態
Azure Storage Blob	使用短效期、最小權限的 container SAS URL，並透過 sas_url_env 指向環境變數或 .env
Azure Static Web App	使用 SWA_CLI_DEPLOYMENT_TOKEN 或自訂 token 環境變數
Any Website (FTP)	使用 NOW_FTP_USERNAME 與 NOW_FTP_PASSWORD 環境變數

now config set 會拒絕明顯像祕密的 key。now config set azure_blob.sas_url <url> 只作為安全便利入口，會把實際 URL 寫入已被 .gitignore 排除的 .env，不會寫入 .now.json。

---

疑難排解

問題	處理方式
provider CLI 找不到	安裝對應 CLI，並確認它在 PATH 內
沒有部署權限	先用 provider CLI 完成登入與權限確認
找不到預設 URL	設定 default_url 或 base_url，或確認 provider 設定足以推導公開 URL
npm 安裝時下載 release asset 失敗	確認版本對應的 GitHub Release asset 已發布
checksum 驗證失敗	刪除安裝快取後重裝，並確認 release asset 與 .sha256 來自同一個版本

macOS DNS 快取異常時，可先執行：

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

---

開發者指南

需求：

rustc --version
cargo --version
node --version
npm --version

常用流程：

make check
make test
make release-build
make npm-pack
make install
make install-local

make install 會把 release binary 安裝到 $HOME/.local/bin/now。若要改安裝 prefix，使用 PREFIX=/custom make install-local。

release asset 命名必須固定：

now-aarch64-apple-darwin.tar.xz
now-aarch64-apple-darwin.tar.xz.sha256
now-x86_64-apple-darwin.tar.xz
now-x86_64-apple-darwin.tar.xz.sha256
now-x86_64-unknown-linux-gnu.tar.xz
now-x86_64-unknown-linux-gnu.tar.xz.sha256
now-x86_64-pc-windows-msvc.zip
now-x86_64-pc-windows-msvc.zip.sha256

CI 會執行 Rust format、clippy、Rust 測試與 npm 測試。release workflow 會建立跨平台 binary archive 與 checksum，發布 GitHub Release 資產成功後，再直接呼叫可重用的 npm publish workflow。npm publish workflow 也保留帶入 release tag 的手動執行入口，並使用：

npm publish --provenance --access public

---

授權與貢獻

本專案採用 MIT License。

貢獻前請先執行：

make check