Mac 上使用 python 工具 uv

uv 是一個新的 Python 工具鏈，透過 效能優化、功能整合與使用者友善設計，簡化了 Python 專案的開發、依賴管理和發布流程。

MacOS 安裝 uv

最簡單的方式是使用 homebrew 安裝 uv

brew install uv

透過 uv 特定版本的 python

安裝好後可以查看已安裝的 python 版本

# 查看已安裝的 python 版本
uv python list

cpython-3.14.0a7-macos-aarch64-none                 <download available>
cpython-3.14.0a7+freethreaded-macos-aarch64-none    <download available>
cpython-3.13.3-macos-aarch64-none                   <download available>
cpython-3.13.3+freethreaded-macos-aarch64-none      <download available>
cpython-3.13.2-macos-aarch64-none                   /opt/homebrew/bin/python3.13 -> ../Cellar/python@3.13/3.13.2/bin/python3.13
cpython-3.13.2-macos-aarch64-none                   /opt/homebrew/bin/python3 -> ../Cellar/python@3.13/3.13.2/bin/python3
cpython-3.12.10-macos-aarch64-none                  <download available>
cpython-3.12.7-macos-aarch64-none                   /opt/homebrew/bin/python3.12 -> ../Cellar/python@3.12/3.12.7_1/bin/python3.12
cpython-3.11.12-macos-aarch64-none                  .local/share/uv/python/cpython-3.11.12-macos-aarch64-none/bin/python3.11
cpython-3.10.17-macos-aarch64-none                  <download available>
cpython-3.10.15-macos-aarch64-none                  /opt/homebrew/bin/python3.10 -> ../Cellar/python@3.10/3.10.15/bin/python3.10
cpython-3.9.22-macos-aarch64-none                   <download available>
cpython-3.9.6-macos-aarch64-none                    /usr/bin/python3

安裝特定版本的 python

uv python install 3.11

透過 uv 建立專案有兩種方式: - 和原有的 pip 和 venv 相容的方式 - 直接使用 uv 管理

搭配 pip 和 venv 建立專案

# 指定 python 版本，建立專案語法
uv venv --python=<version> <env-name>
# 範例
uv venv --python=3.12 .venv

這種方式的缺點是沒有記錄 python 版本，但實際上在 .venv/pyvenv.cfg 可以查看相關設定，但沒有記錄到版控。

# 安裝套件
uv pip install requests

直接使用 uv 管理

# 初始化專案
uv init --python 3.11

會直接建立專案的 git 設定，同時建立專案設定檔 pyproject.toml。

# 加入套件
uv add requests

加入任一套件後會自動建立 .venv 資料夾，並把虛擬環境建立起來。同時把安裝的套件記錄在 pyproject.toml。 pyproject.toml 的角色類似 nodejs 專案的 package.json。其他常用的指令如下：

# 查看 uv 用法
uv -h

# 移除套件
uv remove <套件>
uv remove requests

# 執行指令或程式
uv run <程式或指令>
uv run main.py

# 更新特定套件
uv lock --upgrade-package requests

# 更新所有套件
uv lock --upgrade

nginx 反向代理 fastapi 和 ollama 服務

uvicorn 和 fastapi

使用 Uvicorn 要注意的大概就是 proxy_set_header 那邊的設定。其他 https 的部份，請使用 Certbot 幫忙搞定。

server {
    server_name domain.shinder.cc; # managed by Certbot

    add_header Accept-Ranges bytes;
    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_cache off;
    }

    listen [::]:443 ssl ipv6only=on; # managed by Certbot
    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/domain.shinder.cc/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/domain.shinder.cc/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot
}

server {
    if ($host = domain.shinder.cc) {
        return 301 https://$host$request_uri;
    } # managed by Certbot

    listen 80 ;
    listen [::]:80 ;
    server_name domain.shinder.cc;
    return 404; # managed by Certbot
}

ollama

一般為了安全性 ollama 服務是不對外的。在此的情境是，想讓遠端使用資源，但限定 IP。對外開放的通訊埠為 11435。

server {
    server_name _;

    add_header Accept-Ranges bytes;
    location / {
        proxy_pass http://127.0.0.1:11434;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_buffering off;
        proxy_cache off;

        allow   192.168.1.100;  # 允許 192.168.1.100 訪問
        deny    all;             # 拒絕所有其他 IP 訪問
    }

    listen [::]:11435;
    listen 11435;
}

Ubuntu 重新開機後以 pm2 重啟行程

一般建議使用 systemd 來設定，這裡記錄一下 pm2 的作法。

# 1. 啟動設定，pm2 會依使用的系統，寫入啟動的 script (例如 systemd)
# 這部份可以免除複雜的設定，交給 pm2 處理就好
pm2 startup

# 2. 以 pm2 啟動你要執行的行程，通常是 Nodejs 應用
pm2 start index.js --name mfee62_3000

# 3. 儲存設定
pm2 save
# pm2 會依據目前記憶體內正在執行的行程，儲存一個記錄檔以利重開機後重啟這些行程

使用 homebrew 安裝 apache2 和 php 環境

XAMPP 的 mac 版本現在都比較老舊，而且在 macOS 15 有無法啟動 apache 的問題。 為了教學需求，在此記錄 mac 的 php 環境的建立方式。假設 homebrew 的環境已經安裝完成。 如果要使用 ubuntu vm 可以參考上一篇 https://qops.blogspot.com/2025/03/orbstack-ubuntu-224-php-56-apache2.html 的作法。

安裝 apache2

# 先查看是否已安裝
brew info apache2
# 前幾行若出現 Not installed 表示沒有安裝，後面也有設定的說明

# 安裝
brew install apache2
# 安裝後，注意預先的設定
# -- DocumentRoot is /opt/homebrew/var/www
# -- 主設定檔位置 /opt/homebrew/etc/httpd/httpd.conf
# -- ssl 設定檔位置 /opt/homebrew/etc/httpd/extra/httpd-ssl.conf
# -- 預設的 ports 為 8080 和 8443

# 啟動服務
brew services start httpd
# 在瀏覽器上查看 http://localhost:8080

# 重新啟動服務
brew services restart httpd

# 停止服務
brew services stop httpd

安裝 php

這裡是以 php 8.3 的版本為例說明，當然你可以自行決定要安裝的版本。

# 先查看要安裝的版本資訊
brew info php@8.3

# 安裝
brew install php@8.3

# 在 apache 的設定檔，放入下式
LoadModule php_module /opt/homebrew/opt/php@8.3/lib/httpd/modules/libphp.so

<FilesMatch \.php$>
    SetHandler application/x-httpd-php
</FilesMatch>

# 設定索引檔
DirectoryIndex index.php index.html

PHP 的設定檔位於 /opt/homebrew/etc/php/8.3/ 裡面。

# 若要使用 php 指令，可以將下兩行放入用戶設定檔 (.zshrc) 裡 
export PATH="/opt/homebrew/opt/php@8.3/bin:$PATH"
export PATH="/opt/homebrew/opt/php@8.3/sbin:$PATH"

在根目錄 /opt/homebrew/var/www 寫一支 phpinfo() 檔測試看看。

mysql 8.0

# 先查看要安裝的版本資訊
brew info mysql@8.0

# 安裝
brew install mysql@8.0

# 啟動服務
brew services start mysql@8.0

OrbStack 安裝 Ubuntu 22.4, php 5.6 及 apache2

某個專案還在老舊的 php 5.6 環境，macOS 15 Sequoia 目前已無法正常執行 XAMPP。在不小心升級 macOS 後，測試 php 5.6 程式是讓人困擾的問題。

原本想要使用 OrbStack 的 docker containers 功能，然而 container 需要不少設定，反而是一種麻煩的做法。後來還是以 VM 的方式來處理。OrbStack 的安裝就不贅述。

安裝 ubuntu vm

# *** 安裝 ubuntu vm ***
# orb create --help
# orb create [flags] DISTRO[:VERSION] [MACHINE_NAME]
orb create ubuntu:jammy  # 預設的 machine name 為 ubuntu

# *** 從 mac ssh 連線 vm ***
# ssh [用戶名]@[虛擬主機名]@orb
ssh root@ubuntu@orb

# *** 使用 vm 的 domain ***
# ping [虛擬主機名].orb.local
ping ubuntu.orb.local
# mac host 的 ip 可以直接使用區域網路 ip

在 vm 中可以透過 /mnt/mac 路徑找到 mac 的對應檔案。

安裝 php 5.6

以 ssh 登入 vm 後，依下列步驟安裝 php 5.6

# *** 1. 更新系統 repo 資料
apt update

# *** 2. 安裝 software-properties-common 以管理 PPA (Personal Package Archives)
apt install software-properties-common

# *** 3. php 5.6 已經不是官方維護的版本，需依賴 PPA
add-apt-repository ppa:ondrej/php

# *** 4. 再更新系統 repo 資料一次
apt update

# *** 5. 安裝 php 5.6
apt install php5.6

# *** 6. 安裝 php 常用套件
apt install php5.6-mysql php5.6-curl php5.6-json php5.6-cgi php5.6-xml php5.6-mbstring php5.6-gd

# *** 7. 確認 php 版本
php -v

# *** 8. 啟用 apache2 模組
# 在安裝 apache2 之後才可以執行
# a2dismod php8.3 # 若有需要先關閉新模組
a2enmod php5.6

安裝 apache2

apt install apache2

# 啟用 rewrite module
a2enmod rewrite

# /etc/apache2/mods-enabled 裡啟用的模組參考
access_compat.load -> ../mods-available/access_compat.load
alias.conf -> ../mods-available/alias.conf
alias.load -> ../mods-available/alias.load
auth_basic.load -> ../mods-available/auth_basic.load
authn_core.load -> ../mods-available/authn_core.load
authn_file.load -> ../mods-available/authn_file.load
authz_core.load -> ../mods-available/authz_core.load
authz_host.load -> ../mods-available/authz_host.load
authz_user.load -> ../mods-available/authz_user.load
autoindex.conf -> ../mods-available/autoindex.conf
autoindex.load -> ../mods-available/autoindex.load
cache.load -> ../mods-available/cache.load
cache_disk.conf -> ../mods-available/cache_disk.conf
cache_disk.load -> ../mods-available/cache_disk.load
deflate.conf -> ../mods-available/deflate.conf
deflate.load -> ../mods-available/deflate.load
dir.conf -> ../mods-available/dir.conf
dir.load -> ../mods-available/dir.load
env.load -> ../mods-available/env.load
expires.load -> ../mods-available/expires.load
file_cache.load -> ../mods-available/file_cache.load
filter.load -> ../mods-available/filter.load
headers.load -> ../mods-available/headers.load
mime.conf -> ../mods-available/mime.conf
mime.load -> ../mods-available/mime.load
mpm_prefork.conf -> ../mods-available/mpm_prefork.conf
mpm_prefork.load -> ../mods-available/mpm_prefork.load
negotiation.conf -> ../mods-available/negotiation.conf
negotiation.load -> ../mods-available/negotiation.load
php5.6.conf -> ../mods-available/php5.6.conf
php5.6.load -> ../mods-available/php5.6.load
reqtimeout.conf -> ../mods-available/reqtimeout.conf
reqtimeout.load -> ../mods-available/reqtimeout.load
rewrite.load -> ../mods-available/rewrite.load
setenvif.conf -> ../mods-available/setenvif.conf
setenvif.load -> ../mods-available/setenvif.load
socache_shmcb.load -> ../mods-available/socache_shmcb.load
ssl.conf -> ../mods-available/ssl.conf
ssl.load -> ../mods-available/ssl.load
status.conf -> ../mods-available/status.conf
status.load -> ../mods-available/status.load

安裝 Mariadb 10

# *** 1. 更新套件資訊
apt update

# *** 2. 查看可以安裝的子版本
apt-cache policy mariadb-server

# *** 3. 安裝
apt install mariadb-server

# 以 mysql client 使用 root 登入
mysql -uroot

# 變更 root 密碼
ALTER USER 'root'@'localhost' IDENTIFIED BY '你的密碼';

# 建立管理用戶給 phpmyadmin 使用
CREATE USER 'pmauser'@'localhost' IDENTIFIED BY 'pmauser';
GRANT ALL PRIVILEGES ON *.* TO 'pmauser'@'localhost' WITH GRANT OPTION;
FLUSH PRIVILEGES;

# 查看使用者
SELECT User, Host FROM mysql.user;

使用前端 JS 接收 Ollama 回應的 Ndjson 格式

基本上就是使用 fetch API 來處理串流資料，利用 async/await 就可以使用無窮迴圈來處理。

<input type="text" id="chat" value="台灣位於哪裡？" />
<button onclick="startAsk()">開始</button>
<div id="result_div"></div>

const chat = document.querySelector("#chat");
const result_div = document.querySelector("#result_div");
const model = "mistral-nemo";  // ollama 使用的 LLM 模型名稱

const startAsk = async () => {
  const response = await fetch(`http://localhost:11434/api/generate`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ model, prompt: chat.value }),
  });
  if (!response.ok) {
    console.log("回應發生錯誤!!!");
    return;
  }
  // ['content-type', 'application/x-ndjson']
  console.log(...response.headers);

  const reader = response.body.getReader();  // 讀取器
  const decoder = new TextDecoder("utf8");   // 解碼器

  while (true) {
    const { value, done } = await reader.read();
    const json = decoder.decode(value); // 基本上每一行都是 json
    console.log(json);
    try {
      const obj = JSON.parse(json);
      result_div.innerText += obj.response;
    } catch (ex) {
      console.log(ex);
      console.log("不是 JSON:", `---${json}---`);
    }
    if (done) {
      result_div.innerText += "\n\n";
      break;
    }
  }
};

在 M1 macOS上執行 tensorflow 的環境

目前 M3 的晶片都出好一陣子了，想說 M1 跑 tensorflow 應該沒問題。 結果不管是 python 3.11 或 3.12 都無法正常執行使用到 tensorflow 的專案。

爬文都只能爬到 python 3.8 的環境，3.8 也被評為執行 tensorflow 最為穩定的版本。 後來只好安裝 3.8 再使用 3.8 建立虛擬環境。

參考 Apple 官方文件 https://developer.apple.com/metal/tensorflow-plugin/

# 安裝 python 3.8
brew install python@3.8

mkdir proj-dir
cd proj-dir

# 建立虛擬環境
python3.8 -m venv venv
# 啟動虛擬環境
source ./venv/bin/activate

# 安裝 tensorflow 2.12 的版本
pip install tensorflow-macos
# 安裝 tensorflow-metal
pip install tensorflow-metal

測試官方的範例，有出現 Warning 和 Notice 不過可以正常執行。

Apache HTTPS 服務間歇停止的問題

2024-02-01 開始客戶的網站就發生服務中斷的情況（其實這狀況當時應該發生好幾天了）。

主機架在 DigitalOcean 的 SGP1 上，由於 SGP1 網路設備曾有停擺快 2 天的黑記錄；所以一開始就懷疑是不是網路設備不穩。

以往的經驗，通常停止十分鐘左右就會恢復正常，但這次卻不是想像中單純。

服務大概停擺十分鐘後，就恢復正常，但是每隔一到兩小時就發生一次服務停擺，實著讓人頭疼。

一開始是毫無頭緒到底是什麼問題，也發 ticket 給 DO，DO 回應希望進一步提供資料。

懷疑過：網路設備問題、程式沒寫好、SSL 憑證問題、MySQL 資料庫問題等，大伙搞了兩天也沒離清問題點，只發現 HTTPS 受影響，但 HTTP 似乎沒受影響。可是 HTTPS 中斷服務時， HTTP 也變慢了。

大家的想法都一樣，HTTPS 和 HTTP 都是 Apache 伺服器的服務；沒道理 HTTPS 停擺，而 HTTP 正常。所以焦點又被轉移到 SSL 憑證上。

第三天開始，我終於有比較多的時間，從調 MySQL 開始搞了半天，沒什麼進展。 後來在一堆 Apache error log 中，某個停擺時點找到一條：

[Sat Feb 03 23:54:11.819500 2024] [mpm_prefork:error] [pid 8964] AH00161: server reached MaxRequestWorkers setting, consider raising the MaxRequestWorkers setting

很少在搞設定的我，只好查一下資料 mpm_prefork 是什麼模組，然後網路上也沒查到上面的錯誤會造成什麼問題。 後來在 stackoverflow 找到這篇 AH00161: server reached MaxRequestWorkers setting, consider raising the MaxRequestWorkers setting。

硬著頭皮依照建議設定 mpm_prefork.conf，心想應該就是這個問題。 一覺起來，果然有改善，再依 log 做些調整。

# prefork MPM
# StartServers: number of server processes to start
# MinSpareServers: minimum number of server processes which are kept spare
# MaxSpareServers: maximum number of server processes which are kept spare
# MaxRequestWorkers: maximum number of server processes allowed to start
# MaxConnectionsPerChild: maximum number of requests a server process serves

<IfModule mpm_prefork_module>
    StartServers              10
    MinSpareServers           10
    MaxSpareServers           20
    ServerLimit             2000
    MaxRequestWorkers       1536
    MaxConnectionsPerChild 10000
</IfModule>

幾天的心情低落就因為一個設定。

另一個有趣的事情，就是在 stackoverflow 找資料時，看到一篇症狀和我們遇到的差不多狀況。 但傻眼的是，他自己解答自己的問題，答案是「公司找到會設定 Apache 的人才，他弄一下設定就好了」，沒有提到任何的模組或設定...

RemixJS 使用 Jotai 取代 Context

把之前的專案，用 Jotai 取代 Context 做登入狀態的管理。原本的登入狀態是使用 cookie-session 處理的。

基本上，改用 Jotai 程式碼反而變多了，思路比較徧向以前端的方式解決問題。

以下是遇到的狀況和問題：

1. 要將 loader 取得的資料放到 store，應該要使用 useHydrateAtoms hook。

2. 使用 store.get() 或 store.set() 時，似乎不會觸發 re-render；而必須使用 useAtom，應該是訂閱功能做在 useAtom 身上吧。

3. 使用 Context 時，有些功能用後端功能處理就可以了；但 Jotai 必須使用前端的功能解決。例如登出時，使用 Context 只要在 logout 頁面的 loader() 處理即可。使用 Jotai 必須登出後，使用 useAtom 去變更 store 狀態。使用 google 登入時，有相同的問題。

4. 經常遇到 Warning: Text content did not match 的問題。解決的方式是在使用 useAtom 的 setter 後，再使用 useNavigate 轉到別的頁面，讓頁面重新 render。

RemixJS, Cloudflare Pages 專案使用 Google Sign-in

承上篇的環境設定，要使用 Google sign-in 但不使用官方套件 google-auth-library。

可以使用 worker-auth-providers，它雖然還在 beta 版，但簡單的 oauth 登入是可行的。

GCP 基本設定

Google Cloud Platform (GCP) 設定並下載憑證資料：

1. 到「API 程式庫」>「公開」>「社交」啟用 Google People API。

2. 到「API和服務 > 憑證」，點選「+建立憑證」>「OAuth 用戶 ID」。

3. 「應用程式類型」選「網頁應用程式」

4. 「已授權的 JavaScript 來源」加入正式環境及測試環境的 URI。

5. 「已授權的重新導向 URI」加入接收 Query String 參數的頁面 URI，同樣包含測試及正式環境。

6. 建立完成後，「下載 OAuth 用戶端」的 JSON 檔。

7. 到「OAuth 同意畫面」，設定應用程式名稱，及測試帳號等。

登入頁面

按了「Google 登入」的按鈕轉到 google-signin.tsx 頁面

// app/routes/google-signin.tsx
import { type LoaderFunctionArgs, redirect } from "@remix-run/cloudflare";
import { google } from "worker-auth-providers";
import { getMySession } from "~/utils/sessions";

export async function loader({ request, context, params }: LoaderFunctionArgs) {
  const session = await getMySession(request);
  const userId = session.get("userId");
  if (userId) {
    return redirect("/");
  }
  const env: any = context.env;
  const googleLoginUrl = await google.redirect({
    options: {
      clientId: env.GOOGLE_CLIENT_ID,
      redirectTo: env.GOOGLE_REDIRECT_URI,
    },
  });
  return redirect(googleLoginUrl);
}

用戶登入後轉向的頁面

//
import { type LoaderFunctionArgs, redirect } from "@remix-run/cloudflare";
import { getMySession, getHeadersWithSetCookie } from "~/utils/sessions";
import { google } from "worker-auth-providers";
import getSupabase from "~/utils/supabase-client";

export async function loader({ request, context, params }: LoaderFunctionArgs) {
  const env: any = context.env;
  const { user, tokens } = await google.users({
    options: {
      clientSecret: env.GOOGLE_CLIENT_SECRET,
      clientId: env.GOOGLE_CLIENT_ID,
      redirectUrl: env.GOOGLE_REDIRECT_URI,
    },
    request,
  });

  // "user": {
  //   "id": "111******",
  //   "email": "shinder.lin@gmail.com",
  //   "verified_email": true,
  //   "name": "Shinder Lin",
  //   "given_name": "Shinder",
  //   "family_name": "Lin",
  //   "picture": "...",
  //   "locale": "zh-TW"
  // },

  // console.log({ user, tokens });

  // tokens: {
  //   access_token: 'ya29...',
  //   expires_in: 3599,
  //   scope: 'https://www.googleapis.com/auth/userinfo.email https://www.googleapis.com/auth/userinfo.profile openid',
  //   token_type: 'Bearer',
  //   id_token: 'eyJh...'
  // }

  if (!user?.id) {
    return redirect("/login");
  }

  const supabase = getSupabase(context);

  const { data: data1, error: error1 } = await supabase
    .from("g_users")
    .select()
    .eq("gid", user.id);
  // 是否已經登入過
  if (data1.length) {
    const row: any = data1[0];
    if (row.blocked) {
      return { msg: "您的帳號已被停權" };
    } else {
      await supabase
        .from("g_users")
        .update({ updated_at: new Date() })
        .eq("gid", row.gid);
    }
  } else {
    const { data: data2, error: error2 } = await supabase
      .from("g_users")
      .insert({ gid: user.id, email: user.email, name: user.name })
      .select();
    if (!data2.length) {
      return { msg: "DB 無法新增資料" };
    }
  }

  const session = await getMySession(request);
  session.set("gid", user.id);
  session.set("userId", user.email);
  session.set("nickname", user.name);
  const headers = await getHeadersWithSetCookie(session);
  return redirect('/', { headers });
}

RemixJS, Supabase 專案發佈到 Cloudflare Pages

注意的事項

條列一下，Remix 從專案建立到發佈到 Cloudflare pages 該注意的事項：

1. 建立專案時，直接使用 Cloudflare 的官方工具 npm create cloudflare，以方便發佈，參考Deploy a Remix site。

2. 原本由 @remix-run/node 匯入的類型 LinksFunction, LoaderFunctionArgs 或函式 json, redirect 改由 @remix-run/cloudflare 匯入。

3. 和 NodeJS 相依的套件，儘量不要使用，例如 qs 套件。如果用到了，要在 remox.config.js 裡設定 polyfill。

4. 開發時，環境變數設定在 .dev.vars 裡。在正式環境時，須到 Cloudflare pages 的專案裡，設定環境變數。

5. 環境變數的取得，不是透過 process.env，是透過 context.env。而 context 物件是由 LoaderFunctionArgs 或 ActionFunctionArgs ({ request, context, params }) 而來。

在測試的專案用到 bcryptjs，而該套件使用到 Node 的 crypto，因此要如下設定：

// remox.config.js
/** @type {import('@remix-run/dev').AppConfig} */
export default {
  /* 略 */
  browserNodeBuiltinsPolyfill: { modules: { crypto: true } }, // bcryptjs 需要
};

Supabase 相關

連線 supabase

// app/utils/supabase-client.ts
import { createClient } from "@supabase/supabase-js";

let supabase;

export default function getSupabase(context={}){
  if(! supabase) {
    supabase = createClient(
      context.env.SUPABASE_URL,
      context.env.SUPABASE_ANON_KEY
    );
  }
  return supabase;
}

新增

  const result = await supabase
    .from("address_book")
    .insert({ name, email, mobile, birthday, address, creator_gid: myAuth.gid })
    .select();

讀取

算數量

let totalRows = 0;
const tmpSupabase = supabase
  .from("address_book")
  .select("*", { count: "exact", head: true });

if (searchStr) {
  const { count } = await tmpSupabase.or(
    `name.like.%${searchStr}%,mobile.like.%${searchStr}%`
  );
  totalRows = count;
} else {
  const { count } = await tmpSupabase;
  totalRows = count;
}

條件搜尋

if (searchStr) {
  const { data, error } = await supabase
    .from("address_book")
    .select()
    .or(`name.like.%${searchStr}%,mobile.like.%${searchStr}%`)
    .order("sid", { ascending: false })
    .range((page - 1) * perPage, page * perPage - 1);
  if (!error) {
    rows = data;
  }
} else {
  const { data, error } = await supabase
    .from("address_book")
    .select()
    .order("sid", { ascending: false })
    .range((page - 1) * perPage, page * perPage - 1);
  if (!error) {
    rows = data;
  }
}

更新

let query = supabase
  .from("address_book")
  .update({ name, email, mobile, birthday, address })
  .eq("sid", sid);
let result;
if (myAuth.gid === context.env.ADMIN_GID) {
  result = await query;
} else {
  result = await query.eq("creator_gid", myAuth.gid);
}

刪除

let result;
let query = supabase.from("address_book").delete().eq("sid", sid);
if (myAuth.gid === context.env.ADMIN_GID) {
  result = await query;
} else {
  result = await query.eq("creator_gid", myAuth.gid);
}

RemixJS 2 保有登入狀態

呈上篇 RemixJS 2 以 session 實作登入機制，session 的資料存放在 cookie 裡，那要如何在頁面內判斷及保有登入的狀態？

在前端可以用原本 react 的處理方式，以 context 來保有狀態。在後端必須每個 request 都要檢查 cookie。

get-auth.ts 是將解讀 cookie 的功能寫成模組，用來判斷是否為登入狀態。

// app/modules/get-auth.ts
import { getMySession } from "~/modules/sessions";

async function getAuth(request: Request) {
  const session = await getMySession(request);
  const userId = session.get("userId") || "";
  const nickname = session.get("nickname") || "";
  return { userId, nickname, auth: !!userId };
  // auth 屬性用來判斷是否登入
}

export default getAuth;

AuthContextProvider

// app/contexts/AuthContext.tsx
import React, { createContext } from "react";

export type AuthDataType = {
  userId: string | undefined;
  nickname: string | undefined;
};

export const AuthContext = createContext<AuthDataType>({
  userId: "",
  nickname: "",
});

type PropsType = {
  userId: string | undefined;
  nickname: string | undefined;
  children: React.ReactNode;
};

export function AuthContextProvider({ userId, nickname, children }: PropsType) {
  return (
    <AuthContext.Provider value={{ userId, nickname }}>
      {children}
    </AuthContext.Provider>
  );
}

將 <AuthContextProvider> 包住 <Outlet />。

// app/root.tsx 部份內容
export async function loader({ request, params }: LoaderFunctionArgs) {
  console.log("App loader");
  return await getAuth(request);
}
export default function App() {
  const loaderData = useLoaderData<typeof loader>()
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <AuthContextProvider userId={loaderData.userId} nickname={loaderData.nickname}>
          <Outlet />
        </AuthContextProvider>
        <ScrollRestoration />
        <Scripts />
        <LiveReload />
      </body>
    </html>
  );
}

防止未授權而使用功能

這裡要分兩個部份 loader 和 action。loader 因為有階層關係，可以在 Layout 的 loader 做阻擋的動作。

// app/routes/address-book.tsx 的 loader 部份
export async function loader({ request, params }: LoaderFunctionArgs) {
  console.log("address-book loader");
  const myAuth = await getAuth(request);
  if (!myAuth.auth) {
    // 沒有登入，轉到登入頁面
    return redirect(`/login?u=${request.url}`);
  }
  return null;
}

action 就必須在每個頁面處理。

export async function action({ request, params }: ActionFunctionArgs) {
  const myAuth = await getAuth(request);
  if (!myAuth.auth) {
    // 沒有登入，轉到登入頁面
    return redirect(`/login?u=${request.url}`);
  }
  // 略
}

RemixJS 2 以 session 實作登入機制

一般是以 cookie 存放 session id，session 資料存放在後端，可以是記憶體、檔案或資料庫。 但如果考慮到分散式架構，記憶體和檔案都是不可行的。

以識別用戶而言，其實資料很少一個變數值即可，其餘想放的資料頂多三四個變數值。此時使用官方範例的 createCookieSessionStorage 是個不錯的作法，將資料直接放在 cookie 並加密即可，當然除了好的加密密碼，cookie 最好設定為 httpOnly。

session 工具

使用官方的範例，同時包裝兩個方法 getMySession 和 getHeadersWithSetCookie 省點囉唆的動作。

// app/modules/sessions.ts
import { Session, createCookieSessionStorage } from "@remix-run/node";

type SessionData = {
  userId: string;
  nickname: string;
};
type SessionFlashData = {
  error: string;
};

const { getSession, commitSession, destroySession } =
  createCookieSessionStorage<SessionData, SessionFlashData>({
    cookie: {
      name: "__session",
      // domain: "remix.run",
      // expires: new Date(Date.now() + 60_000),
      httpOnly: true,
      // maxAge: 60,
      path: "/",
      sameSite: "lax",
      secrets: ["your_secret_key"],
      // secure: true,
    },
  });

const getMySession = async (request: Request) => {
  return await getSession(request.headers.get("Cookie"));
};

const getHeadersWithSetCookie = async (session: Session) => {
  return {
    "Set-Cookie": await commitSession(session),
  };
};

export {
  getSession,
  commitSession,
  destroySession,
  getMySession,
  getHeadersWithSetCookie,
};

登入頁

關於登入頁幾點請注意：

1. 進入登入頁前，先判斷用戶是否已經登入，若是則轉向別的頁面。
2. 表單有兩個欄位 email 和 password，email 為 userId。
3. 帳號和密碼直接寫在程式碼裡是不好的作法，這只是個 demo。
4. 確定登入後，將兩個值寫入 cookie，分別是 userId 和 nickname。

// app/routes/login.tsx
// 略
export async function loader({ request, params }: LoaderFunctionArgs) {
  const session = await getMySession(request);
  const userId = session.get("userId");
  if (userId) {
    // 如果已經登入
    const uStr = getQueryStringObject(request)["u"];
    if (uStr) {
      return redirect(uStr);
    } else {
      return redirect("/");
    }
  }
  return null;
}

export default function LoginPage() {
  // 略
  return (
    <>
      <Form method="post" encType="multipart/form-data">
        {/* 略 */}
        <button type="submit" className="btn btn-primary">
          登入
        </button>
      </Form>
    </>
  );
}
type loginUser = { email: string; nickname: string; password: string };

export async function action({ request, params }: ActionFunctionArgs) {
  const users: loginUser[] = [
    { email: "lsd0125@gmail.com", password: "12345678", nickname: "小嘟" },
    { email: "shin@gmail.com", password: "345678", nickname: "肥肥" },
  ];
  const session = await getMySession(request);

  const body = await getBodyObject(request);
  const { email, password } = body;
  const theUser = users.find((u) => {
    return u.email === email && u.password === password;
  });

  const output = {
    success: !!theUser,
    bodyData: body,
  };

  if (theUser) {
    session.set("userId", email);
    session.set("nickname", theUser.nickname);
    const headers = await getHeadersWithSetCookie(session);
    return json(output, { headers });
  }

  return output;
}

登出功能

登出是直接把兩個值從 cookie 中移除。

// app/routes/logout.tsx
import { type LoaderFunctionArgs, redirect } from "@remix-run/node";
import { getMySession, getHeadersWithSetCookie } from "~/modules/sessions";
import { getQueryStringObject } from "~/modules/handle-request-data";

export async function loader({ request, params }: LoaderFunctionArgs) {
  const session = await getMySession(request);
  session.unset("userId");
  session.unset("nickname");
  const headers = await getHeadersWithSetCookie(session);
  const uStr = getQueryStringObject(request)["u"];
  if(uStr){
    return redirect(uStr, { headers });
  } else {
    return redirect("/", { headers });
  }
}

有 userId 後，其它要存放在後端的資料，就可以存到資料庫裡了，不要把太多資料放在 cookie 裡，通常不要超過 4K。

RemixJS 2 的 .env

Remix 在 開發環境 是直接支援 .env 的。

但要特別注意，在 production 時是忽略 .env 的。變通的方式很多，可以用 shell script 或 dotenv-cli 工具。

RemixJS 2 action 函式

loader() 的功能是在以 GET 拜訪時，於後端執行，通常是取得頁面要使用的資料。action() 則是用來處理 GET 方法以外的要求。

實作 API

在沒有頁面的 component function，action() 和 loader() 可以用來建立 RESTful API。以下是個刪除功能的例子。

// app/modules/mysql-connect.ts // 用以建立資料庫連線
import mysql, { PoolOptions } from "mysql2/promise";

const options: PoolOptions = {
  host: process.env.DB_HOST,
  user: process.env.DB_USER,
  password: process.env.DB_PASS,
  database: process.env.DB_NAME,
  waitForConnections: true,
  connectionLimit: 10,
  queueLimit: 0,
  enableKeepAlive: true,
  keepAliveInitialDelay: 0,
};
const pool = mysql.createPool(options);

export default pool;

// app/routes/address-book.delete.$sid.tsx
import { type ActionFunctionArgs } from "@remix-run/node";
import db from "./../modules/mysql-connect";

export async function action({ request, params }: ActionFunctionArgs) {
  const output = {
    success: false,
    result: {},
  };
  const sid = params.sid;
  if (request.method === "DELETE") {
    if (sid && parseInt(sid)) {
      const sql = `DELETE FROM address_book WHERE sid=${sid}`;
      const [result] = await db.query(sql);
      output.result = result;
      output.success = true;
    }
  }
  return output;
}

搭配頁面表單使用

action() 可以搭配頁面內的表單 (使用 Form 元件) 做回應，在一般情況下是以 AJAX 的方式溝通。以下是一個範例的部份程式碼。

import type { LoaderFunctionArgs, ActionFunctionArgs } from "@remix-run/node";
import {
  useLoaderData,
  Form,
  useActionData,
} from "@remix-run/react";
import { getBodyObject } from "~/modules/handle-request-data";

export async function loader({ request, params }: LoaderFunctionArgs) {
  // 載入資料
}

export default function AddressBookEdit() {
  const data = useLoaderData();
  const actionData = useActionData<typeof action>();
  // ...
  return (
    <div className="container">
      <Form method="post" encType="multipart/form-data">
        <div className="mb-3">
          <label htmlFor="email" className="form-label">
            email
          </label>
          <input
            type="text"
            className="form-control"
            id="email"
            name="email"
            value={form.email}
            onChange={handleFieldChange}
          />
        </div>
        <button type="submit" className="btn btn-primary">
          修改
        </button>
      </Form>
    </div>
  );
}

export async function action({ request, params }: ActionFunctionArgs) {
  const sid = params.sid;
  const body = await getBodyObject(request);
  const { name, email, mobile, birthday, address } = body;
  const output = {
    success: false,
    result: {},
    bodyData: body,
  };
  // 變更資料
  return output;
}

注意幾個要點：

1. 表單必須使用 @remix-run/react 的 Form 元件建立。
2. 和一般表單一樣可以使用 encType 屬性決定送出的資料編碼方式。
3. 可以使用 action 屬性設定表單傳送的對象 (可以不是該頁面的 action() 函式)。
4. 在頁面內使用 useActionData() 取得表單送出後回傳的訊息或資料。
5. 若要實作 RESTful API 可以依 request.method 是 POST、PUT 或 DELETE 來做不同的處理。

RemixJS 2 處理從用戶端來的資料

handle-request-data.ts 包含了幾個處理要求端來的資料，後來改用 qs 套件比較符合 expressjs 的風格。 其中處理上傳檔案的部份為存成檔案，目前建議存到雲端服務，例如 AWS S3。 這些函式同樣可以使用在 NextJS app router 上。

// *** handle-request-data.ts
import qs from "qs";
import fs from "node:fs/promises";
import { v4 as uuidV4 } from "uuid";

export const getQueryStringObject:any = (request: Request) => {
  const q = request.url.indexOf("?");
  if (q < 0) {
    return {};
  } else {
    return qs.parse(request.url.slice(q+1));
  }
  // *** 以下為使用 Object 的版本
  // const url = new URL(request.url);
  // return Object.fromEntries(url.searchParams);
};

export const getBodyObject = async (request: Request) => {
  const contentType = request.headers.get("Content-Type")?.split(";")[0];

  switch (contentType) {
    case "multipart/form-data":
      const formData:any = await request.formData();
      return qs.parse(new URLSearchParams(formData).toString());
      // *** 以下為使用 Object 的版本
      // return Object.fromEntries(formData);

    case "application/x-www-form-urlencoded":
      const txt = await request.text();
      return qs.parse(txt);
      // *** 以下為使用 Object 的版本
      // const usp = new URLSearchParams(txt);
      // return Object.fromEntries(usp);

    case "application/json":
      const json = await request.json();
      return json;
  }
};

type FileDataType = {
  size: number;
  type: string;
  lastModified: number;
  originalName: string;
  filename: string;
  path: string;
};
type MultipartDataResultType = {
  fields: { [index: string]: string | string[] };
  files: { [index: string]: FileDataType | FileDataType[] };
  error: any;
};

// *** 處理檔案上傳
export async function getMultipartData(
  request: Request,
  acceptedMimeTypes = ["image/jpeg", "image/png"], // 篩選類型設定
  useUuidFilename = true, // 使用隨機 uuid 為主檔名
  uploadDir = "./tmp" // 上傳的資料夾
) {
  let result: MultipartDataResultType = {
    fields: {},
    files: {},
    error: {},
  };
  const method = request.method.toUpperCase();

  let type = request.headers.get("Content-Type");
  if (!type) return result;
  type = type.split(";")[0]; // 取得 mimetype

  if (method !== "GET") {
    if (type === "multipart/form-data") {
      const formData = await request.formData();
      try {
        await fs.access(uploadDir, fs.constants.F_OK);
      } catch (ex) {
        // 建立上傳的資料夾
        await fs.mkdir(uploadDir, { recursive: true });
      }

      for (const [k, v] of formData.entries()) {
        console.log({ k, v });
        if (typeof v === "string") {
          // 處理文字欄位
          if (!result.fields[k]) {
            result.fields[k] = v;
          } else {
            if (result.fields[k] instanceof Array) {
              const strArray = result.fields[k] as string[];
              strArray.push(v);
            } else {
              const val = result.fields[k] as string;
              result.fields[k] = [val, v];
            }
          }
        } else if (v instanceof Blob) {
          // 處理檔案欄位
          result.files = result.files || {};
          const { size, type, name, lastModified } = v;

          if (acceptedMimeTypes.length) {
            if (!acceptedMimeTypes.includes(type)) {
              continue;
            }

            let filename = name;
            if (useUuidFilename) {
              let tmpName = name.toLowerCase();
              let mainName = uuidV4();
              let extName = "";
              if (tmpName.indexOf(".") !== -1) {
                const frs = tmpName.split(".");
                extName = "." + frs[frs.length - 1];
              }
              filename = mainName + extName;
            }
            const path = uploadDir + "/" + filename;
            const fileData: FileDataType = {
              size,
              type,
              lastModified,
              originalName: name,
              filename,
              path,
            };

            if (!result.files[k]) {
              result.files[k] = fileData;
            } else {
              if (result.files[k] instanceof Array) {
                const fdArray = result.files[k] as FileDataType[];
                fdArray.push(fileData);
              } else {
                const val = result.files[k] as FileDataType;
                result.files[k] = [val, fileData];
              }
            }
            await fs.writeFile(path, v.stream() as any);
          }
        }
      }
    }
  }
  return result;
}

RemixJS 2 裡的 link 和 meta 標籤

SSR 的特色是可以讓每個頁面擁有各自的 SEO 設定，同時也可以有各自的 link 和 meta 設定。

link 標籤

可以在 root.tsx 使用 links() 設定整個網站都通用的 link 標籤。

export const links: LinksFunction = () => [
  ...(cssBundleHref ? [{ rel: "stylesheet", href: cssBundleHref }] : []),
  {
    rel: "stylesheet",
    href: "https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css",
  },
  {
    rel: "stylesheet",
    href: "https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.4.2/css/all.min.css",
  },
];

在 Layout 架構中，links() 的功能是堆疊起來的，以下式的架構來說明。

app/root.tsx
app/routes/address-book.tsx
app/routes/address-book.add.tsx

/address-book/add 的頁面最後取得的 link 標籤會依序是三個檔加起來的設定。

meta 標籤

meta 標籤的運作則和 link 標籤不同，在 root.tsx 可以直接設定全站的 meta 標籤。 <Meta /> 是用來載入子元件的 meta 設定。

// root.tsx 片段
export default function App() {
  const loaderData = useLoaderData<typeof loader>()
  return (
    <html lang="en">
      <head>
        <meta charSet="utf-8" />
        <meta name="viewport" content="width=device-width, initial-scale=1" />
        <Meta />
        <Links />
      </head>
      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
        <LiveReload />
      </body>
    </html>
  );
}

但在 Layout 的結構中，meta() 並不會疊加之前的設定，而是以最後設定的為主。 另外，在同一個檔案 loader() 會比 meta() 先執行，所以 meta() 可以收到 loader() 回傳的資料。

export const meta: MetaFunction = ({ data, params, location, matches }) => {
  console.log("address-book meta");
  console.log(data);  // { shin: "der" }
  return [
    { title: "通訊錄" },
    { name: "keyword", content: "address-book" },
    { name: "name", content: "shin" },
  ];
};
export async function loader({ request, params }: LoaderFunctionArgs) {
  console.log("address-book loader");
  return { shin: "der" };
}

RemixJS 2 loader 函式

RemixJS 使用 react ，是架構簡潔的 SSR (Server Side Render) 框架。 它的每個頁面都有可能是 SSR 或 CSR (Client Side Render)，所以有特殊的兩個後端執行的函式 loader() 和 action()，頁面內的 components 則無。

loader() 的功能是在以 GET 拜訪時，於後端執行，通常是取得頁面要使用的資料。頁面裡 React component 可以使用 useLoaderData() hook 載入 loader() 回傳的資料。

loader() 並非必要的函式。另外，若沒有要回傳資料必須回傳 null。

// app/routes/address-book.edit.$sid.tsx
import { type LoaderFunctionArgs, redirect } from "@remix-run/node";
import { useLoaderData } from "@remix-run/react";
import dayjs from "dayjs";
import db from "~/modules/mysql-connect";
import { RowDataPacket } from "mysql2/promise";

export async function loader({ request, params }: LoaderFunctionArgs) {
  const sid = params.sid;
  const sql = `SELECT * FROM address_book WHERE sid=?`;
  const [rows] = await db.query<RowDataPacket[]>(sql, [sid]);
  if (rows.length) {
    rows[0].birthday = dayjs(rows[0].birthday).format("YYYY-MM-DD");
    return rows[0];  // useLoaderData() 可以取得此處回傳的資料
  } else {
    return redirect("/address-book");
  }
}

export default function AddressBookEdit() {
  const data = useLoaderData();
  return (
    <div className="container">
     </div>
  );
}

Layout 的 loader()

每層的 Layout 都有可能需要個別的資料呈現，所以每層的 loader() 會依序觸發。以檔案 app/routes/address-book.add.tsx 為例。依序會觸發下列檔案的 loader()。

app/root.tsx
app/routes/address-book.tsx
app/routes/address-book.add.tsx

然而，依邏輯 Layout 不應該有 action()，就算有也不會依機制呼叫。

API功能 (沒有頁面函式時)

如果該路由不是要呈現 HTML 頁面，而是提供 JSON 格式的資料時，可以只定義 loader() 而不定義頁面 react component 函式。

import {
  type LoaderFunctionArgs,
  json,
} from "@remix-run/node";

export async function loader({ request, params }: LoaderFunctionArgs) {
  return json({ name: "Shinder", method: request.method });
}

RemixJS 2 的路由架構

NestJS 13 推出 app router 架構快一年了，把原本 "資料夾" 和 "檔案" 設定並存的方式，大刀闊斧改成以資料夾為主的路由設定方式。

反之，RemixJS 2 則是轉向以 "檔案" 為主的路由設定方式。如果以中小型網站的角度去看，RemixJS 似乎是比較方便的做法。以下是整理官方文件的說明。

以檔案為基本架構

檔案資料夾結構

app/
├── routes/
│   ├── _index.tsx
│   ├── about.tsx
│   ├── concerts._index.tsx
│   ├── concerts.$city.tsx
│   ├── concerts.trending.tsx
│   └── concerts.tsx
└── root.tsx

URL路徑	對應的檔案	Layout (佈局檔)
/	app/routes/_index.tsx	app/root.tsx
/about	app/routes/about.tsx	app/root.tsx
/concerts	app/routes/concerts._index.tsx	app/routes/concerts.tsx
/concerts/trending	app/routes/concerts.trending.tsx	app/routes/concerts.tsx
/concerts/salt-lake-city	app/routes/concerts.$city.tsx	app/routes/concerts.tsx

歸納幾點規則：

1. 根目錄檔案為 _index.tsx
2. 檔案名稱中以點「.」做為分隔的符號，表示路徑的分段。 concerts.trending.tsx 表示 /concerts.trending 路徑。
3. 動態路由使用美金符號為分段開頭，例如上表中的 concerts.$city.tsx。
4. 經過的佈局檔，會由 root.tsx 為最開頭。以 app/routes/concerts.trending.tsx 為例，經過的佈局檔會為 root.tsx 再來才是 concerts.tsx。佈局檔和葉路由檔會分別被編譯為個別的 js 檔以方便動態載入。

下表為更複雜的狀況：

URL路徑	對應的檔案
/address-book/edit/abc	app/routes/address-book.edit.abc.tsx
/address-book/edit/123	app/routes/address-book.edit.$sid.tsx
/address-book/edit/abc/def	app/routes/address-book.edit.abc.def.tsx

以資料夾為架構

也可以使用資料夾為架構，不過只能在 routes 目錄下的第一層，更內層的資料夾就沒有效果了。 資料夾的命名規則同上述的檔案命名規則，而對應的頁面檔案名稱需為 route.tsx。

app/
├── routes/
│   ├── _index/
│   │   ├── signup-form.tsx
│   │   └── route.tsx
│   ├── about/
│   │   ├── header.tsx
│   │   └── route.tsx
│   ├── concerts/
│   │   ├── favorites-cookie.ts
│   │   └── route.tsx
│   ├── concerts.$city/
│   │   └── route.tsx
│   ├── concerts._index/
│   │   ├── featured.tsx
│   │   └── route.tsx
│   └── concerts.trending/
│       ├── card.tsx
│       ├── route.tsx
│       └── sponsored.tsx
└── root.tsx

自訂路由

一般使用預設路由規則即可，在某些情況下要自訂路由對應可以設定 remix.config.js 檔，請參考官方文件說明。

NextJS app router 實作 body-parser 功能

承上篇，NextJS 的 app router 所使用的 request 和 response 分別是 NextRequest 和 NextResponse 類型；又分別是 JS 裡 Request 和 Response 類型的延伸。所以解析 http body 要遵循 Request 和 Response 類型的 api 用法。

底下的工具，借用 qs 套件的功能解析 urlencoded 的格式。實作了三個功能：

1. getQueryString(): 解析 query string parameters
2. getBodyData(): 解析表單資料（包含 multipart 格式）
3. getMultipartData(): 解析上傳的表單

// *** request-parser.js
import qs from "qs";
import fs from "node:fs/promises";
import { v4 as uuidV4 } from "uuid";

/** 解析 query string */
export function getQueryString(request) {
  return qs.parse(request.url.split("?")[1]);
}

/** 解析 urlencoded, json, multipart */
export async function getBodyData(request) {
  let result = {};
  const method = request.method.toUpperCase();
  const type = request.headers.get("Content-Type");
  if (method !== "GET") {
    if (type === "application/x-www-form-urlencoded") {
      const txt = await request.text();
      result = txt.length ? qs.parse(txt) : {};
    } else if (type === "application/json") {
      try {
        result = await request.json();
      } catch (ex) {}
    } else {
      const { fields } = await getMultipartData(request);
      if (fields) result = { ...fields };
    }
  }
  return result;
}

/** 解析 multipart  */
export async function getMultipartData(
  request, // NextRequest 物件
  acceptedMimetypes = [], // 篩選類型設定，預設為不篩選
  useUuidFilename = true, // 使用隨機 uuid 為主檔名
  uploadDir = "./tmp" // 上傳的資料夾
) {
  let result = {
    fields: undefined,
    files: undefined,
    error: undefined,
  };
  const method = request.method.toUpperCase();

  let type = request.headers.get("Content-Type");
  if (!type) return result;
  type = type.split(";")[0]; // 取得 mimetype

  if (method !== "GET") {
    if (type === "multipart/form-data") {
      const formData = await request.formData();
      try {
        await fs.access(uploadDir, fs.constants.F_OK);
      } catch (ex) {
        // 建立上傳的資料夾
        await fs.mkdir(uploadDir, { recursive: true });
      }

      for (const [k, v] of formData.entries()) {
        if (typeof v === "string") {
          // 處理文字欄位
          result.fields = result.fields || {};
          if (!result.fields[k]) {
            result.fields[k] = v;
          } else {
            if (result.fields[k] instanceof Array) {
              result.fields[k].push(v);
            } else {
              result.fields[k] = [result.fields[k], v];
            }
          }
        } else if (v instanceof Blob) {
          // 處理檔案欄位
          result.files = result.files || {};
          const { size, type, name, lastModified } = v;
          if (acceptedMimetypes.length) {
            if (!acceptedMimetypes.includes(type)) {
              continue;
            }

            let filename = name;
            if (useUuidFilename) {
              let tmpName = name.toLowerCase();
              let mainName = uuidV4();
              let extName = "";
              if (tmpName.indexOf(".") !== -1) {
                const frs = tmpName.split(".");
                extName = "." + frs[frs.length - 1];
              }
              filename = mainName + extName;
            }
            const path = uploadDir + "/" + filename;
            const fileData = {
              size,
              type,
              lastModified,
              originalName: name,
              filename,
              path,
            };

            if (!result.files[k]) {
              result.files[k] = fileData;
            } else {
              if (result.files[k] instanceof Array) {
                result.files[k].push(fileData);
              } else {
                result.files[k] = [result.files[k], fileData];
              }
            }
            await fs.writeFile(path, v.stream());
          }
        }
      }
    }
  }
  return result;
}

以下是在 route.js 中的用法範例。

import {
  getBodyData,
  getQueryString,
  getMultipartData,
} from "@/modules/request-parser";

const responseInit = {
  status: 200,
  headers: {
    "Content-Type": "application/json",
  },
}

export async function GET(request) {
  let output = getQueryString(request);

  return new Response(JSON.stringify(output), responseInit);
}

export async function POST(request) {
  let body = await getBodyData(request);
  return new Response(JSON.stringify(body), responseInit);
}

export async function PUT(request) {
  let multi = await getMultipartData(request, ["image/jpeg"]);
  return new Response(JSON.stringify(multi), responseInit);
}