一個智能的 Chrome 擴展，精準將網頁內容保存至 Notion。具備強大的智能內容提取功能，結合 Readability 與獨家演算法，為絕大多數網頁提供純淨的正文與圖片保存體驗；同時針對結構複雜的網站（如 BBC、明報、HK01、Yahoo 香港新聞等，持續擴展中）提供深度優化支持，並可持久保存遷移的多色標註功能。
🚀 快速開始 | 🎬 功能展示 | ✨ 核心功能 | 📖 使用指南 | 🛠️ 技術特性 | 🔧 開發說明 | 🤝 貢獻
查看最新功能和改進：所有版本發布說明
📖 完整使用指南 | 包含詳細操作說明、FAQ 和故障排除
方法一：Chrome 商店安裝（推薦）
- 訪問 Chrome Web Store - Save to Notion 🔗
- 點擊「加到 Chrome」即可安裝
方法二：開發者模式安裝
- 從 Releases 下載最新版本
- 打開
chrome://extensions/，開啟「開發者模式」 - 點擊「載入未封裝項目」，選擇下載的資料夾
💡 首次安裝會自動開啟引導頁，依序協助你完成 Notion 授權、選擇預設儲存資料庫；中途任何一步都可以跳過。已熟悉設定流程的用戶也能直接照下方手動步驟操作。
👉 方式 A：快捷授權 (推薦，支援 OAuth 一鍵登入)
⚠️ 注意：此一鍵登入功能僅支援官方發布的版本（包含 Chrome 商店與 GitHub Releases 載點）。若您使用的是自行編譯的 Fork 或二次開發版本，請使用下方的「方式 B」，或查閱文末的「自訂 Notion OAuth」開發說明。
- 點擊擴展圖標 →
⚙️ 設定→ 點擊「🔌 連接到 Notion」 - 在跳轉的 Notion 官方頁面完成授權並選擇工作區
- 回到擴展的設定介面，選擇目標資料庫（Data Source），點擊「保存設置」
👉 方式 B：手動輸入 Integration Token (傳統方式)
- 訪問 Notion Integrations 頁面創建 Integration，並複製 Internal Integration Token
- 點擊擴展圖標 →
⚙️ 設定，將 Token 貼入輸入框並保存 - 重要：在 Notion 目標資料庫頁面右上角
...中，將該 Integration 加入 Connections 中
📖 詳細配置步驟與問題排查請參考 → 完整使用指南
💡 點擊圖片可查看大圖
- CSS Highlight API：使用瀏覽器原生功能，零 DOM 修改，完美跨元素支持
- 多顏色標註：4 種顏色（🟡黃、🟢綠、🔵藍、🔴紅），適應不同使用場景
- 自定義樣式：支持背景顏色、文字顏色、底線三種模式，適應暗色模式與個人偏好
- 同步Notion：標記變更同步到 Notion 頁面
- 雙重刪除：雙擊刪除或 Ctrl/Cmd + 點擊快速刪除
- Next.js原生支持：深度解析 Next.js (App Router/Pages Router) 網站數據，精準還原高品質內容
- 深度優化：針對 BBC、HK01、明報、Yahoo HK 等複雜網站特別優化，提供網域專屬清洗規則支援完整、乾淨的內容保存
- Mozilla Readability：智能提取文章主要內容，支持多種 CMS 系統
- DOMPurify 安全消毒：集中清洗 HTML 與 SVG，移除不安全標籤、屬性與協定，降低 XSS 風險
- 自動過濾：自動過濾廣告和無關內容
- 完整保存：支持超長文章（8000+ 字），自動分批處理
- 網站 Icon：自動提取網站 favicon/logo 顯示在 Notion 頁面標題旁
- 封面圖識別：自動識別文章封面圖（支持 20+ 種選擇器）
- 智能過濾：自動排除作者頭像和無關圖片
- 格式支持：懶加載、響應式、代理 URL 自動處理
- 標題模板：支持變量（
{title}、{date}、{domain}等） - 內容選項：可添加時間戳和來源信息
- 預覽功能：即時查看模板效果
- OAuth 認證：支援新版 Notion OAuth 安全授權，內建 Token 自動刷新與過期防護機制
- 儲存與備份：內建增強的存儲管理，支援擴展配置的自動備份與還原功能；支援本地標注備份與還原
包含詳細的操作步驟、常見問題與故障排除、以及實用的達人技巧。推薦所有用戶閱讀！
快速連結:
- 🚀 快速開始 - 安裝和配置步驟
- 🎯 核心功能與使用情境 - 功能詳細說明與情境展示
- 💡 達人技巧 - 工作流優化建議
- ❓ 常見問題與故障排除 - 疑難排解與常見問題解答
- 瀏覽到想保存的網頁，點擊擴展圖標
- 點擊「保存頁面」，等待完成（擴展圖標會顯示綠色 "✓"）
- 點擊「在 Notion 中打開」可直接打開保存的頁面
- 點擊「開始標註」啟用標註模式
- 選擇標註顏色（🟡黃色、🟢綠色、🔵藍色、🔴紅色）
- 選中文字自動創建標註（支持跨段落選擇）
- 點擊「同步」將標記保存到 Notion
- 刪除標註：
- 雙擊標記文本後確認刪除
- 或按住 Ctrl/Cmd + 點擊快速刪除
在「設定」頁面配置標題模板（如 [{domain}] {title}）和內容選項，點擊「預覽效果」查看結果
- Manifest V3：使用最新的 Chrome 擴展標準
- ES6 模組化：核心系統已重構為獨立模組，提升可維護性
- Preloader：
< 5KB全域注入，負責快捷鍵監聯與性能預熱 - 按需載入：主程式僅在需要時載入，大幅降低記憶體佔用
- Range API：精確的文本位置記錄和恢復
- URL 正規化：移除追蹤參數（
utm_*、gclid、fbclid等）
notion-chrome/
├── .github/ # CI 與 workflow（ci.yml、release-please.yml）
├── manifest.json # 擴展配置與權限（Manifest V3）
├── rollup/ # Rollup 構建配置（all/content/background/migration + shared factories）
├── dist/ # 打包產物
│ ├── preloader.js # 全域輕量預載腳本
│ ├── content.bundle.js # Content Script 統一打包版
│ ├── migration-executor.js # Migration 執行入口
│ ├── scripts/background.js # Background service worker bundle
│ └── pages/ # Extension pages final entry points
│ ├── popup.js
│ ├── options.js
│ ├── sidepanel.js
│ ├── onboarding.js
│ ├── update-notification.js
│ └── auth.js
├── pages/ # 擴展頁面集合（popup / sidepanel / options / onboarding / update-notification）
│ ├── popup/ # 彈出窗口 UI（處理 API 調用與 DOM 更新）
│ ├── sidepanel/ # 側邊欄 UI（常駐顯示保存狀態、支援快速操作與頁面同步）
│ ├── options/ # 設置頁面 UI（模塊化設置邏輯：Auth, DataSource, Storage 等）
│ ├── onboarding/ # 首次安裝引導頁
│ └── update-notification/ # 更新通知頁面與邏輯
├── scripts/ # 核心腳本與子模組
│ ├── background.js # 處理擴展邏輯、API 調用、模板處理與更新通知
│ ├── background/ # 模塊化背景服務
│ │ ├── services/ # 服務層 (Notion, Storage, Injection, Tab, PageContent)
│ │ ├── handlers/ # 業務處理器 (Save, Highlight, Migration)
│ │ └── utils/ # 背景工具 (BlockBuilder)
│ ├── content/ # 模塊化內容提取系統 (產出: dist/content.bundle.js)
│ │ ├── index.js # 入口文件
│ │ ├── extractors/ # 提取層 (ContentExtractor, ReadabilityAdapter, ImageCollector 等)
│ │ ├── converters/ # 轉換層 (ConverterFactory, DomConverter)
│ │ └── adapters/ # 適配層 (整合 Readability.js 等)
│ ├── config/ # 跨模組共享配置 (shared constants, DOM selectors, runtime actions, storage keys)
│ ├── highlighter/ # 基於 CSS Highlight API 的新一代標註引擎 (產出: dist/highlighter-v2.bundle.js)
│ │ ├── core/ # 核心模組 (Range, HighlightManager, Storage 等)
│ │ ├── ui/ # Content UI (Floating Rail, legacy Toolbar fallback, components, styles)
│ │ └── utils/ # 工具模組 (color, dom, textSearch 等)
│ ├── performance/ # 性能優化模組
│ └── utils/ # 工具模組 (Logger, Security, ErrorHandler, ImageUtils)
├── icons/ # 圖標
├── promo-images/ # 宣傳圖片（Chrome Web Store）
├── tests/ # 測試文件（2500+ tests）
├── README.md # 用戶說明
└── CHANGELOG.md # 版本變更記錄
# 克隆倉庫
git clone https://github.com/cowcfj/save-to-notion.git
cd save-to-notion
# 安裝依賴（會自動執行構建）
npm install
# → postinstall hook 會自動執行 npm run build
# → dist/highlighter-v2.bundle.js 與 dist/content.bundle.js 自動生成
# 產生本地測試用的最小 unpacked extension
npm run package:local-unpacked
# 或直接更新可載入的本地測試 extension
npm run ext
# 載入 Chrome Extension
# Chrome → 擴展程式 → 開啟開發者模式 → 載入未封裝項目 → 選擇 .tmp/extension-unpacked# 🔥 推薦：實時編譯（同時監控 Highlighter 與 Content Script）
npm run dev
# 或 npm run build:watch
# 修改源碼 (scripts/highlighter/ 或 scripts/content/)
# → 自動重新打包到 dist/
# → 重新載入 Extension 即可看到變更
# 一次性構建（開發版本，未壓縮）
npm run build
# 生產構建（Terser 壓縮）
npm run build:prod
# 生產構建 + bundle 分析報告
npm run build:prod:analyze
# 產生本地測試用的最小 unpacked extension
npm run package:local-unpacked
# 運行測試
npm test
# 若要直接執行 npx jest，請先跑 npm install，確保 scripts/config/env/build.js 已由 postinstall 生成
# 代碼檢查
npm run lint自動構建機制：
- ✅
npm install後自動執行npm run build - ✅
npm run package:local-unpacked可生成本地測試用的最小載入目錄（完全排除scripts/原始碼，大幅減少 package 體積，消除雙軌） - ✅
dist/目錄不被追蹤（在.gitignore中）
開發時的最佳實踐：
# 1. 開啟實時編譯（推薦，會自動涵蓋所有 pages 打包）
npm run dev
# 2. 修改代碼（可修改 content script、highlighter、或頁面 JS）
vim scripts/highlighter/core/Range.js
# 或修改頁面 JS
vim pages/popup/popup.js
# 3. 查看 Terminal 確認重新打包
# ✅ created dist/content.bundle.js in 40ms
# ✅ created dist/pages in 530ms
# 4. 重新載入 Extension（Chrome Extension 頁面點擊刷新圖標）本地載入建議：
MUST載入.tmp/extension-unpackedMUST NOT直接載入 repo root- 建議日常使用
npm run ext更新本地測試 extension - 原因：repo root 會把
node_modules、docs、coverage、.git等大型目錄一併算進 Chrome 顯示的擴展大小，誤導本地體積與效能判讀 - 若要固定本地測試 extension ID，可將 dev public key 放在
$HOME/.config/notion-chrome/dev-extension-public-key.txt
本項目使用 Rollup 進行模組打包：
-
開發環境：
npm run build:watch- 實時監控文件變更
- 不壓縮代碼
- inline source map
-
生產環境：
npm run build:prod- Terser 壓縮（-91% 體積）
- Migration bundle 不產出 production sourcemap
- 保留 console.log（除錯用）
- 保留關鍵全局變數
-
分析模式：
npm run build:prod:analyze- 產出
.tmp/bundle-analysis/*.html - 用於檢查 bundle 組成與體積來源
- 產出
構建配置：rollup.config.mjs
開源版與官方生產版的建置環境已完全分離。為避免依賴無法公開的官方後端代理，開源版預設會隱藏 OAuth 按鈕（僅顯示傳統的「手動填寫 Integration Token」）。
如果您希望在自己開發的版本中啟用 Notion OAuth 一鍵登入，請按照以下步驟設定：
-
部署自己的 OAuth 代理伺服器：
-
您需要實作一個後端服務（如 Cloudflare Worker）來安全保管您的
client_secret，並代理 Notion 的/v1/oauth/token與/v1/oauth/refresh請求。 -
安全建議：為了防止他人濫用您的代理伺服器，請自行生成一組專屬的金鑰（API Key），並在您的後端服務中檢查請求標頭
X-Extension-Key是否與該金鑰相符。 -
💡 查看 Cloudflare Worker 代理伺服器範例
我們準備了一份可以直接複製使用的 Cloudflare Worker 代理程式碼範例，其中已包含 CORS 處理與基本的安全性防護，可大幅節省您的建置時間。
-
-
申請 Notion Public Integration：
- 在 Notion Integrations 頁面建立一組 Public API，取得
client_id。
- 在 Notion Integrations 頁面建立一組 Public API，取得
-
配置本地環境變數：
- 首次執行
npm install後，專案會自動將模板複製為scripts/config/env/build.js。 - 開啟
scripts/config/env/build.js，將尾段的BUILD_ENV區塊修改為您的專屬配置：export const BUILD_ENV = Object.freeze({ ENABLE_OAUTH: true, // 👈 將此設為 true 以在設定頁顯示 OAuth 按鈕 ENABLE_ACCOUNT: true, // 👈 將此設為 true 以在設定頁顯示帳號登入按鈕 OAUTH_SERVER_URL: 'https://your-oauth-proxy-url.com', // 👈 填寫您的後端代理伺服器網址 OAUTH_CLIENT_ID: 'your-notion-client-id', // 👈 填寫您的 Notion Client ID EXTENSION_API_KEY: 'your-custom-header-key', // 👈 步驟 1 自訂的防濫用過濾值，會以 `X-Extension-Key` Header 送出。注意它隨擴充功能公開打包、非真正 secret，僅用於擋廉價濫用。 });
- 首次執行
-
重新打包並載入：若您處於
npm run dev開發模式，存檔後即會自動重新打包。刷新擴充功能後，即可在設定頁中看到生效的 OAuth 登入選項。
歡迎提交 Issue 和 Pull Request 來改進這個項目！
請查看我們的 隱私政策 了解更多資訊。
本專案採用 GPLv3 授權。如果您需要將其整合至閉源商業產品，請與我聯繫取得商業授權（Dual Licensing）。
This extension relies on the following open-source projects:
-
@mozilla/readability Used for extracting main content from web pages. Licensed under the Apache License 2.0. Copyright (c) 2010 Arc90 Inc.
-
DOMPurify Used for HTML and SVG sanitization to help prevent XSS in content extraction and highlighter UI paths. Licensed under the Apache License 2.0 or Mozilla Public License 2.0.