Update

.env.example

@@ -172,6 +172,16 @@
 # MAILCHIMP_API_KEY=    
 # NEXT_PUBLIC_DEBUG=
 # ENABLE_CACHE=
+# NEXT_PUBLIC_CLAUDE_README_CACHE_ENABLED=
+# NEXT_PUBLIC_CLAUDE_CONTRIBUTION_PERSIST_ENABLED=
+# NEXT_PUBLIC_CLAUDE_CONTRIBUTION_EVENT_LIMIT=50000
+# CLAUDE_CONTRIBUTION_FORCE_REFRESH=false
+# CLAUDE_CONTRIBUTION_TRIGGER_TOKEN=
+# SUPABASE_URL=
+# SUPABASE_SECRET_KEY=
+# NEXT_PUBLIC_SUPABASE_URL=
+# NEXT_PUBLIC_SUPABASE_PUBLISHABLE_DEFAULT_KEY=
+# SUPABASE_SERVICE_ROLE_KEY=
 # VERCEL_ENV=
 # NEXT_PUBLIC_VERSION=
 # NEXT_BUILD_STANDALONE=

.github/FUNDING.yml

@@ -1,2 +1,3 @@
 # These are supported funding model platforms
 ko_fi: tangly1024
+buy_me_a_coffee: tangly1024

.github/workflows/bump-version-on-main.yml

@@ -0,0 +1,48 @@
+# 每次向 main 推送（含合并 PR）后，自动将 package.json 最后一位小版本 +1。
+# 自动提交信息含 [skip-version]，避免无限循环。发正式版或大版本时请人工改版本号后再合并。
+
+name: Bump package version on main
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+concurrency:
+  group: bump-package-version-main
+  cancel-in-progress: false
+
+jobs:
+  bump-patch:
+    runs-on: ubuntu-latest
+    # 跳过自动发版机器人自己的提交，防止循环触发
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (github.event.head_commit != null &&
+       !contains(github.event.head_commit.message, '[skip-version]'))
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Bump package.json patch (last segment)
+        run: node scripts/bump-package-patch-version.js
+
+      - name: Commit and push if changed
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if git diff --quiet package.json; then
+            echo "No version change (unexpected)."
+            exit 0
+          fi
+          NEW_VER=$(node -p "require('./package.json').version")
+          git add package.json
+          git commit -m "chore(release): bump package.json to ${NEW_VER} [skip-version]"
+          git push

.gitignore

@@ -53,6 +53,10 @@ package-lock.json
 # yarn.lock
 
 .notion-api-lock
+.tmp/
+.perf/
+tsconfig.tsbuildinfo
+webpack-internal:/
 
 # TypeScript build info
 tsconfig.tsbuildinfo

.npmrc

@@ -1 +1,2 @@
+package-lock=false
 engine-strict=true

.nvmrc

@@ -1 +1 @@
-20
+20.18.0

.yarnrc.yml

@@ -0,0 +1,2 @@
+enableImmutableInstalls: false
+nodeLinker: node-modules

CONTRIBUTING.md

@@ -18,6 +18,22 @@ To contribute to NotionNext, follow these steps:
 5. Commit your modifications and push the branch.
 6. [Create a PR][pr] from the branch in your fork to NotionNext' `main` branch.
 
+## Required Workflow Rules
+
+Please follow these rules for every contribution:
+
+1. Create a dedicated branch for each task (do not commit directly to `main`).
+2. Keep PRs focused and minimal (avoid mixing unrelated refactors/config edits).
+3. Do not commit personal/local files such as `.env.local`.
+4. Do not submit personalized config defaults that can affect other contributors.
+5. Run lint/tests before opening PR.
+
+For full Chinese workflow guidance, see:
+
+- [Docs Navigation](./docs/README.md)
+- [Contribution Workflow](./docs/CONTRIBUTION_WORKFLOW.md)
+- [Configuration Rules](./docs/CONFIGURATION.md)
+
 This project is built with [Next.js][next.js] and `yarn` as the package manager.
 Here are some commands that you can use:
 

CONTRIBUTING.zh-CN.md

@@ -0,0 +1,66 @@
+# 贡献指南（中文）
+
+- [环境准备](#环境准备)
+- [新建主题](#新建主题)
+- [新增语言](#新增语言)
+- [环境变量](#环境变量)
+
+感谢你愿意为 NotionNext 做贡献！
+
+## 环境准备
+
+请按以下流程参与开发：
+
+1. 在 GitHub 上 Fork 仓库。
+2. 克隆到本地（或使用 Codespaces）。
+3. 为本次任务创建独立分支。
+4. 完成功能或修复并本地验证。
+5. 提交并推送分支。
+6. 发起 PR 到 NotionNext 的 `main` 分支。
+
+常用命令：
+
+- `yarn`：安装依赖
+- `yarn dev`：本地开发
+- `yarn build`：生产构建
+- `yarn start`：生产模式运行
+
+## 必须遵守的协作规则
+
+1. 每个任务使用独立分支，禁止直接提交到 `main`。
+2. PR 保持聚焦，避免把无关重构混在一起。
+3. 不要提交个人本地文件（如 `.env.local`）。
+4. 不要提交会影响他人的个性化默认配置。
+5. 提交前至少执行 lint / type-check / 必要测试。
+
+更多文档导航：
+
+- [文档导航入口（中文）](./docs/README.md)
+- [Docs Navigation (English)](./docs/README.en.md)
+- [主题迁移指南（中文）](./docs/THEME_MIGRATION_GUIDE.zh-CN.md)
+- [Theme Migration Guide (English)](./docs/THEME_MIGRATION_GUIDE.md)
+
+## 新建主题
+
+如果要贡献新主题，请以 `themes/example` 为基础复制一个新目录，目录名即主题 key。
+
+## 新增语言
+
+如需新增本地化语言：
+
+1. 复制 `lib/lang/en-US.js` 并按语言代码重命名（如 `zh-CN.js`）。
+2. 完成文本翻译。
+3. 在 `lib/lang.js` 注册该语言。
+4. 提交 PR。
+
+## 环境变量
+
+1. 复制 `.env.example` 为 `.env.local`。
+2. 按需填写配置。
+3. 不要提交 `.env.local`。
+
+配置优先级：
+
+1. Notion 配置表（最高）
+2. 环境变量
+3. `blog.config.js`（最低）

DEPLOYMENT.md

@@ -6,6 +6,23 @@ NotionNext 支持多种部署方式，本指南将详细介绍各种部署选项
 
 ## 部署前准备
 
+### 0. 本地统一基线（推荐）
+
+为提升跨平台兼容性（Vercel / Cloudflare Pages / Netlify / EdgeOne Pages 等），本项目建议统一使用以下最简流程：
+
+```bash
+# Node 20（版本以仓库根目录 `.nvmrc` 为准，便于与各平台预装列表对齐）
+nvm use || nvm install
+
+# Yarn
+npm i -g yarn
+
+# 安装依赖 / 本地开发 / 构建
+yarn
+yarn dev
+yarn build
+```
+
 ### 1. 环境变量配置
 
 创建 `.env.local` 文件并配置必要的环境变量：
@@ -30,16 +47,16 @@ NEXT_PUBLIC_ANALYTICS_GOOGLE_ID=G-XXXXXXXXXX
 在部署前确保项目能够正常构建：
 
 ```bash
-npm run build
-npm run start
+yarn build
+yarn start
 ```
 
 ### 3. 质量检查
 
 运行完整的质量检查：
 
 ```bash
-npm run quality
+yarn quality
 ```
 
 ## Vercel 部署（推荐）
@@ -84,9 +101,9 @@ vercel --prod
 ```json
 {
   "framework": "nextjs",
-  "buildCommand": "npm run build",
+  "buildCommand": "yarn build",
   "outputDirectory": ".next",
-  "installCommand": "npm install",
+  "installCommand": "yarn",
   "functions": {
     "pages/api/**/*.js": {
       "maxDuration": 30
@@ -126,7 +143,7 @@ vercel --prod
    - 连接你的 GitHub 仓库
 
 2. **构建设置**
-   - Build command: `npm run build`
+   - Build command: `yarn build`
    - Publish directory: `out`
    - 环境变量: `EXPORT=true`
 
@@ -137,7 +154,7 @@ vercel --prod
 
 ```bash
 # 构建静态文件
-npm run export
+yarn export
 
 # 安装 Netlify CLI
 npm install -g netlify-cli
@@ -158,7 +175,7 @@ netlify deploy --prod --dir=out
 
 ```toml
 [build]
-  command = "npm run export"
+  command = "yarn export"
   publish = "out"
 
 [build.environment]
@@ -178,6 +195,18 @@ netlify deploy --prod --dir=out
   status = 301
 ```
 
+## 腾讯云 EdgeOne Pages
+
+EdgeOne 构建阶段会按仓库中的 `.nvmrc` 切换 Node 版本。若控制台报错类似 **Failed to switch to Node.js x.y.z**，通常是因为平台上 **未提供该补丁版本**（例如仅有 `20.18.0`，而旧版本 `.nvmrc` 写了 `20.20.0`）。
+
+处理方式：
+
+1. **保持上游**：拉取最新 NotionNext，确认 `.nvmrc` 已与 EdgeOne「项目设置 → Node.js 版本」下拉列表中可选版本一致（一般为当前文件中的 `20.18.x`）。
+2. **自建仓库**：在 EdgeOne 控制台选择与 `.nvmrc` **完全一致**的 Node 版本；仍失败时检查构建日志是否仍在读取旧的 `.nvmrc`（需推送后再构建）。
+3. `package.json` 中 `engines.node` 为 `>=20 <25`，在 Node 20 系列内均可构建；关键是 **构建环境实际安装的版本**能解析 `.nvmrc`。
+
+构建命令与静态导出等与其它平台相同，按需配置环境变量（至少 `NOTION_PAGE_ID`）。
+
 ## Docker 部署
 
 ### Dockerfile
@@ -201,7 +230,7 @@ COPY . .
 
 ENV NEXT_TELEMETRY_DISABLED 1
 
-RUN npm run build
+RUN yarn build
 
 # Production image, copy all the files and run next
 FROM base AS runner
@@ -278,7 +307,7 @@ docker-compose up -d
 ### 构建静态文件
 
 ```bash
-npm run export
+yarn export
 ```
 
 ### GitHub Pages 部署
@@ -312,7 +341,7 @@ jobs:
       run: npm ci
 
     - name: Build
-      run: npm run export
+      run: yarn export
       env:
         NOTION_PAGE_ID: ${{ secrets.NOTION_PAGE_ID }}
 
@@ -387,32 +416,32 @@ NEXT_PUBLIC_ANALYTICS_GOOGLE_ID=G-XXXXXXXXXX
 1. **构建失败**
    ```bash
    # 清理缓存
-   npm run clean
+   yarn clean
    rm -rf node_modules package-lock.json
-   npm install
-   npm run build
+   yarn
+   yarn build
    ```
 
 2. **环境变量问题**
    ```bash
    # 检查环境变量
-   npm run quality
+   yarn quality
    ```
 
 3. **内存不足**
    ```bash
    # 增加 Node.js 内存限制
-   NODE_OPTIONS="--max-old-space-size=4096" npm run build
+   NODE_OPTIONS="--max-old-space-size=4096" yarn build
    ```
 
 ### 调试模式
 
 ```bash
 # 启用调试
-DEBUG=* npm run build
+DEBUG=* yarn build
 
 # Next.js 调试
-NEXT_DEBUG=true npm run dev
+NEXT_DEBUG=true yarn dev
 ```
 
 ## 安全检查清单
@@ -430,8 +459,8 @@ NEXT_DEBUG=true npm run dev
 ### 数据备份
 
 ```bash
-# 备份 Notion 数据
-npm run backup-notion
+# 备份数据（按你的脚本体系执行）
+# 例如：node scripts/backup-notion.js
 
 # 备份配置文件
 tar -czf config-backup.tar.gz .env.local blog.config.js
@@ -450,16 +479,16 @@ tar -czf config-backup.tar.gz .env.local blog.config.js
 
 ```bash
 # 检查依赖更新
-npm run check-updates
+yarn check-updates
 
 # 更新依赖
-npm update
+yarn upgrade
 
 # 安全审计
-npm audit
+yarn audit
 
 # 性能分析
-npm run analyze
+yarn bundle-report
 ```
 
 ### 版本升级