build: 将构建工具链从 Bun 切换到 Node.js + pnpm

.github/CODEOWNERS

@@ -2,4 +2,4 @@
 
 *          @jinzhongjia @jiacai2050 @xihale
 *.json     @jinzhongjia
-bun.lock   @jinzhongjia
+pnpm-lock.yaml @jinzhongjia

.github/dependabot.yml

@@ -4,9 +4,8 @@
 # https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
 
 version: 2
-enable-beta-ecosystems: true
 updates:
-  - package-ecosystem: "bun"
+  - package-ecosystem: "npm"
     directory: "/"
     schedule:
       interval: "weekly"

.github/workflows/autocorrect.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Check source code
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
       - name: AutoCorrect
         uses: huacnlee/autocorrect-action@v2

.github/workflows/build.yml

@@ -17,19 +17,31 @@ on:
 
   workflow_call:
 
+# zig build 会执行 PR 中的构建代码，权限收到最小
+permissions:
+  contents: read
+
 jobs:
   build:
     strategy:
       matrix:
-        os: [ubuntu-latest, macos-latest, windows-latest]
+        # macos 固定 15：macos-latest 已迁移到 macOS 26，Zig 在其上链接不到系统
+        # libSystem（所有 libc 符号 undefined），0.11-0.15 全部受影响
+        os: [ubuntu-latest, macos-15, windows-latest]
         version: [0.11.0, 0.12.1, 0.13.0, 0.14.0, 0.15.1]
       fail-fast: false
     runs-on: ${{ matrix.os }}
     steps:
+      # checkout 必须在 setup-zig 之前：checkout 的 clean 会清掉 setup-zig
+      # 恢复的本地 .zig-cache
+      - uses: actions/checkout@v5
+        with:
+          # 不把 github.token 写进 .git/config，避免被 PR 中的构建代码读走
+          persist-credentials: false
       - name: Setup Zig
-        uses: goto-bus-stop/setup-zig@v2
+        uses: mlugg/setup-zig@v2
         with:
           version: ${{ matrix.version }}
-      - uses: actions/checkout@v4
+          cache-key: ${{ matrix.version }}
       - name: Build test
         run: zig build

.github/workflows/check.yml

@@ -5,25 +5,44 @@ on:
   pull_request:
     branches: [main]
 
+# 本工作流会安装依赖并执行 PR 中的代码，权限收到最小
+permissions:
+  contents: read
+
 jobs:
   check:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0 # Not needed if lastUpdated is not enabled
-      - uses: oven-sh/setup-bun@v2
+          persist-credentials: false
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
         with:
-          bun-version: latest
+          node-version: 24
+          cache: pnpm
       - name: Install dependencies
-        run: bun i
+        run: pnpm install --frozen-lockfile
       - name: check
-        run: bun check
+        run: pnpm check
   lint:
     runs-on: ubuntu-latest
     steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Setup Zig
-        uses: goto-bus-stop/setup-zig@v2
+        uses: mlugg/setup-zig@v2
+        with:
+          version: 0.16.0
+      # 0.12 / 0.14 的 assembly.zig 使用旧的内联汇编 clobbers 语法，
+      # 新版 zig 无法解析，只能排除
       - name: Verify formatting
-        run: zig fmt .
+        run: |
+          zig fmt --check \
+            --exclude course/code/12/assembly.zig \
+            --exclude course/code/14/assembly.zig \
+            .

.github/workflows/deploy.yml

@@ -34,17 +34,18 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
         with:
           fetch-depth: 0 # Not needed if lastUpdated is not enabled
-      - uses: oven-sh/setup-bun@v2
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
         with:
-          bun-version: latest
+          node-version: 24
+          cache: pnpm
       - name: Install dependencies
-        run: bun i
+        run: pnpm install --frozen-lockfile
       - name: Build with VitePress
-        run: |
-          bun run build
+        run: pnpm run build
 
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

.github/workflows/release.yml

@@ -15,21 +15,23 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v5
 
-      - name: Setup Bun
-        uses: oven-sh/setup-bun@v2
+      - uses: pnpm/action-setup@v4
+
+      - uses: actions/setup-node@v4
         with:
-          bun-version: latest
+          node-version: 24
+          cache: pnpm
 
-      - name: Install dependencies with Bun
-        run: bun install
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
 
-      - name: Export PDF with Bun
-        run: bun pdf
+      - name: Export PDF
+        run: pnpm pdf
 
-      - name: Export EPUB with Bun
-        run: bun epub
+      - name: Export EPUB
+        run: pnpm epub
 
       - name: Create and Upload Release
         uses: softprops/action-gh-release@v2

.gitignore

@@ -1,6 +1,8 @@
 # 依赖
 node_modules
 package-lock.json
+bun.lock
+yarn.lock
 
 # 构建产物
 dist/
@@ -21,10 +23,10 @@ zig-pkg
 */zig-cache
 */.zig-cache
 
-# PDF 字体源缓存（由 bun pdf:fonts 下载，产物字体单独提交）
+# PDF 字体源缓存（由 pnpm pdf:fonts 下载，产物字体单独提交）
 scripts/pdf/.font-src/
 
-# EPUB 字体下载缓存（bun epub 构建时下载）
+# EPUB 字体下载缓存（pnpm epub 构建时下载）
 course/.vitepress/epub/.cache/
 
 # 工具 / 编辑器 / 系统

AGENTS.md

@@ -68,8 +68,8 @@ zig-course/
 │       ├── autocorrect.yml     # 中文文本格式检查
 │       └── pdf.yml             # PDF 导出流程
 │
-├── package.json                # Node.js 依赖（Bun）
-├── bun.lock                    # Bun 锁文件
+├── package.json                # Node.js 依赖（pnpm）
+├── pnpm-lock.yaml              # pnpm 锁文件
 └── flake.nix                   # Nix 开发环境
 ```
 
@@ -93,34 +93,35 @@ zig build
 
 ```bash
 # 启动带热重载的开发服务器
-bun dev
+pnpm dev
 
 # 构建生产站点
-bun build
+pnpm build
 
 # 预览构建后的站点
-bun preview
+pnpm preview
 
 # 导出 PDF 版本
-bun export-pdf
+pnpm pdf
 ```
 
 ### 代码格式化
 
 ```bash
-# 格式化所有代码（Markdown、Zig、中文文本）
-bun format
+# 格式化 Markdown / TypeScript 与中文文本
+pnpm format
 
 # 检查格式但不修改文件
-bun check
+pnpm check
 ```
 
 这会运行：
 
 - Prettier 处理 Markdown/TypeScript/JavaScript
-- `zig fmt` 处理 Zig 源文件
 - AutoCorrect 处理中文文本格式
 
+Zig 源文件不在 `pnpm format` 范围内，需单独运行 `zig fmt .`。
+
 ## 版本兼容性维护
 
 ### 多版本构建系统架构
@@ -387,13 +388,13 @@ zig build
 zig build test
 
 # 3. 格式化所有文件
-bun format
+pnpm format
 
 # 4. 检查格式
-bun check
+pnpm check
 
 # 5. 本地预览文档
-bun dev
+pnpm dev
 ```
 
 ### 代码片段标记详解
@@ -499,6 +500,6 @@ pub fn main() void {
 
 4. 验证
    zig build          # 编译验证
-   bun format         # 格式化
-   bun dev            # 本地预览
+   pnpm format         # 格式化
+   pnpm dev            # 本地预览
 ```

CONTRIBUTING.md

@@ -8,4 +8,4 @@
 - 等待 review
 - 合并到上游仓库，并由 github action 自动构建
 
-注意：本文档所使用的构建工具为 [bunjs](https://bun.sh/)，在提交时请勿将其他 nodejs 的包管理工具的额外配置文件添加到仓库中。
+注意：本文档所使用的包管理器为 [pnpm](https://pnpm.io/)，在提交时请勿将其他包管理工具的额外配置文件（如 `package-lock.json`、`yarn.lock`）添加到仓库中。

README.md

@@ -83,7 +83,7 @@ zig-course/
 
 ### 环境要求
 
-- **Node.js**: 推荐使用 [Bun](https://bun.sh/) 作为包管理器
+- **Node.js**: 需要 Node.js >= 24（脚本依赖原生 TypeScript 支持），包管理器使用 [pnpm](https://pnpm.io/)
 - **Zig**: 支持 0.11-0.16 版本
 - **autocorrect**: 用于中英文排版优化（可选）
 
@@ -95,25 +95,25 @@ git clone https://github.com/zigcc/zig-course.git
 cd zig-course
 
 # 安装依赖
-bun install
+pnpm install
 
 # 启动开发服务器
-bun dev
+pnpm dev
 
 # 在浏览器中访问 http://localhost:5173
 ```
 
 ### 可用命令
 
 ```sh
-bun run dev          # 启动开发服务器（热重载）
-bun run build        # 构建生产版本
-bun run preview      # 预览构建结果
-bun run format       # 格式化代码（prettier + zig fmt + autocorrect）
-bun run check        # 检查代码格式
-bun run pdf          # 导出 PDF 版本（jsPDF 离线生成 -> books/zig_course.pdf）
-bun run pdf:sample   # 仅渲染几篇代表页快速验证 -> books/zig_course_sample.pdf
-bun run epub         # 导出 EPUB3 电子书 -> books/zig-course.epub
+pnpm run dev          # 启动开发服务器（热重载）
+pnpm run build        # 构建生产版本
+pnpm run preview      # 预览构建结果
+pnpm run format       # 格式化代码（prettier + autocorrect，Zig 代码用 zig fmt 单独格式化）
+pnpm run check        # 检查代码格式
+pnpm run pdf          # 导出 PDF 版本（jsPDF 离线生成 -> books/zig_course.pdf）
+pnpm run pdf:sample   # 仅渲染几篇代表页快速验证 -> books/zig_course_sample.pdf
+pnpm run epub         # 导出 EPUB3 电子书 -> books/zig-course.epub
 ```
 
 ## 🤝 参与贡献
@@ -159,13 +159,13 @@ bun run epub         # 导出 EPUB3 电子书 -> books/zig-course.epub
 3. **进行修改**
    - 遵循现有的代码风格和文档格式
    - 确保所有代码示例都能正常运行
-   - 运行 `bun format` 格式化代码
+   - 运行 `pnpm format` 格式化代码
 
 4. **测试修改**
 
    ```sh
-   bun dev    # 本地测试
-   bun build  # 确保构建成功
+   pnpm dev    # 本地测试
+   pnpm build  # 确保构建成功
    ```
 
 5. **提交更改**
@@ -186,7 +186,7 @@ bun run epub         # 导出 EPUB3 电子书 -> books/zig-course.epub
 ### 贡献规范
 
 - **提交信息**: 使用 [约定式提交](https://www.conventionalcommits.org/zh-hans/) 格式
-- **代码风格**: 运行 `bun format` 确保代码格式一致
+- **代码风格**: 运行 `pnpm format` 确保代码格式一致
 - **文档规范**:
   - 中英文之间添加空格
   - 使用中文标点符号
@@ -223,10 +223,10 @@ bun run epub         # 导出 EPUB3 电子书 -> books/zig-course.epub
 
 ## 📋 开发注意事项
 
-- **包管理器**: 本项目使用 [Bun](https://bun.sh/)，请勿提交其他包管理器的配置文件
-- **依赖更新**: 更新依赖前请参考 [Bun Lockfile 文档](https://bun.sh/docs/install/lockfile)
-- **格式化**: 提交前务必运行 `bun format` 进行代码格式化
-- **构建测试**: 确保 `bun build` 能成功构建
+- **包管理器**: 本项目使用 [pnpm](https://pnpm.io/)，请勿提交其他包管理器的配置文件
+- **依赖更新**: 更新依赖后请一并提交 `pnpm-lock.yaml`
+- **格式化**: 提交前务必运行 `pnpm format` 进行代码格式化
+- **构建测试**: 确保 `pnpm build` 能成功构建
 
 ## 📄 许可证