🐬Spotfire IronPython 出現 unexpected token | 怎麼辦？一次看懂錯誤原因、排查方式與修正方法

Spotfire IronPython 出現 unexpected token `|` 是什麼意思？新手也能看懂的完整解析

在使用 Spotfire 搭配 IronPython 腳本時，有些人會突然遇到一段看起來很可怕的錯誤訊息，例如：


Microsoft.Scripting.SyntaxErrorException: unexpected token '|'

這種錯誤常常讓人很困惑，尤其是剛接觸 Spotfire、IronPython，或是平常主要寫 Java、C#、JavaScript 的工程師，常會一時看不出問題到底在哪裡。

其實，這類錯誤的核心原因通常不複雜。簡單來說，就是：

你的腳本裡用了 IronPython 不接受的 | 符號寫法，所以程式還沒開始執行，就先在「讀程式碼」這個階段卡住了。

這篇文章會用最白話的方式，帶你看懂：

這個錯誤代表什麼
為什麼會發生
哪些情況最常出現
怎麼快速排查
怎麼改成 Spotfire / IronPython 可執行的版本

一、先理解：這不是執行失敗，而是「語法看不懂」

很多人看到長長一串錯誤堆疊，會以為是資料有問題、權限有問題，或 Spotfire 壞掉了。

但這次不是。

這種錯誤屬於 語法錯誤（Syntax Error）。
意思是：系統在執行前，先檢查你的程式碼長什麼樣子，結果看到某個符號時，發現「我不懂這是什麼」，所以直接停止。

你可以把它想像成：

你交了一篇作文給老師
老師還沒開始看內容
一翻開就看到一個根本不屬於這個語言的符號
老師直接說：「這句話語法不成立」

所以重點不是資料內容，而是程式碼寫法本身不符合 IronPython 的語法規則。

二、`|` 為什麼會出錯？

| 這個符號在某些語言或某些版本的 Python 中可以使用，但在 Spotfire 常見的 IronPython 環境裡，很多情境下都不適用。

也就是說：

你以為可以用的寫法，IronPython 不一定支援。

尤其當你是從以下來源複製程式時，更容易踩雷：

一般 Python 3 教學
ChatGPT 產生的現代 Python 寫法
C# 或 JavaScript 習慣帶過來
pandas 篩選語法直接移植到 Spotfire 腳本

三、最常見的 4 種出錯原因

1. 把 `|` 當成「或」來用

很多人寫條件判斷時，直覺會把 | 當作「或者」。

例如下面這種示意寫法：


status = "OPEN"

if status == "OPEN" | status == "NEW":
    print("顯示資料")

這種寫法在 IronPython 裡很容易出錯。

正確觀念是：
在 Python 的條件判斷中，要表達「或」，通常應使用 or，而不是 |。

改寫成下面才是較安全、較標準的方式：


status = "OPEN"

if status == "OPEN" or status == "NEW":
    print("顯示資料")

還可以再進一步寫得更簡潔：


status = "OPEN"

if status in ("OPEN", "NEW"):
    print("顯示資料")

這種寫法通常更好讀，也更不容易出錯。

2. 從其他語言帶進錯誤習慣

如果你平常寫的是 C#、Java、JavaScript，很容易不小心把別的語言習慣帶進 Python。

例如有些人會寫出這種示意程式：


flagA = True
flagB = False

if flagA || flagB:
    print("成立")

這在 Python 裡是錯的。

因為 Python 並不使用 || 來表示「或」，而是使用 or。

正確應改成：


flagA = True
flagB = False

if flagA or flagB:
    print("成立")

雖然這次錯誤訊息提到的是單一 |，但實務上很多人會把這兩種情況混在一起，所以一起檢查最安全。

3. 使用了新版 Python 才支援的語法

這一點很常見，也很容易被忽略。

現在網路上很多 Python 範例，都是用比較新的 Python 版本來寫的。但 Spotfire 常用的 IronPython 並不是最新 Python，因此很多新語法它根本不認得。

例如下面是新版 Python 常見的型別寫法：


user_name: str | None = None

這種寫法在新版本 Python 可以，但在 IronPython 環境中通常會失敗。

對 IronPython 來說，比較安全的方式通常是把這種型別提示拿掉，改成單純的變數指定：


user_name = None

如果真的需要做型別處理，也通常要採用更舊、更保守的寫法，而不是直接用現代 Python 語法。

4. 把 pandas 寫法直接搬到 Spotfire IronPython

有些工程師在 Jupyter Notebook 或一般 Python 專案裡，常會寫 DataFrame 條件過濾。例如會習慣使用 | 去組合條件。

但是 Spotfire 的 IronPython 腳本，很多時候不是在跑 pandas 環境，所以你不能直接把那套寫法原封不動複製過來。

例如像這種資料篩選概念的示意：


# 這是一般資料分析工具常見思路，不一定適合直接搬到 Spotfire IronPython

如果你是在 Spotfire API 裡控制資料表、頁面或篩選，通常要改用 Spotfire 本身可支援的物件操作方式，而不是照搬外部 Python 套件習慣。

這也是為什麼很多人會覺得：

「明明我在別的 Python 環境可以跑，為什麼到 Spotfire 就不行？」

答案通常就是：

因為兩邊不是同一種執行環境。

四、完全不懂程式的人，可以怎麼理解這件事？

你可以把它想成「翻譯官看不懂你的句子」。

你原本想表達的是：

如果狀態是 A，或者狀態是 B，就繼續執行。

但你用了系統不認識的符號寫成一種奇怪句型。
結果翻譯官還沒翻完，就直接說：

這句話格式不合法，我不知道你在寫什麼。

所以系統不是不做事，而是根本無法開始理解你的指令。

五、如何快速找出是哪一行出問題？

遇到這種狀況，最有效率的方法不是盲改，而是直接做這幾件事。

方法 1：全文搜尋 `|`

先打開你的 Spotfire IronPython 腳本，直接搜尋：

只要找到這個符號，就逐一檢查附近的程式碼。

特別注意以下幾種情況：

是否出現在 if 條件裡
是否出現在函式參數型別宣告中
是否是從別的語言貼過來的 ||
是否是新版 Python 的語法
是否是資料過濾條件的寫法

方法 2：先看最近修改過的地方

如果你原本的腳本以前能跑，最近才壞掉，那就幾乎可以確定：

問題通常出在最近新增或修改的幾行。

尤其要回想最近是否做過這些事：

參考網路文章改寫 Python
請 AI 幫你產生程式
從其他專案複製一段程式
加入更進階的條件判斷
增加型別註記

方法 3：把複雜條件拆開

如果一個 if 寫得很長，很容易看不出哪個地方有問題。
這時候可以先拆成多個變數，再判斷。

例如原本你可能寫了一大串條件，建議改成像這樣的示意風格：


is_open = status == "OPEN"
is_new = status == "NEW"

if is_open or is_new:
    print("條件成立")

這樣比較容易看懂，也更容易發現哪裡寫錯。

六、實務上最推薦的改法

如果你在 Spotfire IronPython 裡只是想表達「符合 A 或 B 都可以」，那最穩定的做法通常有兩種。

寫法 1：使用 `or`


region = "TW"

if region == "TW" or region == "JP":
    print("亞洲區資料")

這種寫法直觀，幾乎人人看得懂。

寫法 2：使用 `in`


region = "TW"

if region in ("TW", "JP"):
    print("亞洲區資料")

這種寫法在條件值很多時特別好用，可讀性也很高。

七、為什麼這種問題在 Spotfire 特別常見？

因為 Spotfire 的 IronPython 很容易讓人誤以為：

「這不就是 Python 嗎？」

但實際上，它並不是完整等同於你平常安裝的最新版 Python。

所以常見情況是：

你在網路上找到的 Python 範例可以跑
你在本機 Python 可以跑
但貼進 Spotfire 腳本後卻報語法錯誤

這時不是你完全寫錯，而是執行環境不同。

這種問題在企業環境尤其常見，因為許多商業工具內建的腳本引擎版本不一定新，也不一定完整支援現代語法。

八、排錯時，工程師最容易忽略的觀念

很多人除錯時只盯著錯誤最後一行，但其實真正的關鍵是：

unexpected token | 代表系統看到一個不該出現在那裡的符號。

所以與其一直懷疑資料來源、資料筆數、權限設定，不如先做這件事：

先找出程式裡所有的 |，看它是不是被用在不適合的地方。

通常這一步就能省下大量時間。

九、給新手的簡單判斷口訣

遇到這個錯誤時，可以先記住一個超簡單的判斷方式：

看到 `|`，先問自己三件事：

我是不是想表達「或」？
這裡是不是應該用 or？
這段是不是從新版 Python 或其他語言複製來的？

如果答案有一個是「對」，那問題大概就在這裡。

十、結論：這類錯誤其實不難，只是很容易被嚇到

Microsoft.Scripting.SyntaxErrorException: unexpected token '|'
表面上看起來很可怕，但本質通常很單純：

IronPython 看不懂你使用的 | 寫法。

最常見的修正方向就是：

把 | 改成 or
把多條件改成 in (...)
移除不支援的新版 Python 型別語法
不要直接把其他語言或 pandas 寫法搬進 Spotfire IronPython

只要掌握這些原則，之後再遇到同類型錯誤，就不會那麼慌了。

搜尋此網誌

小小大大學