# offline-portable-pack

**Repository Path**: qianchilang/offline-portable-pack

## Basic Information

- **Project Name**: offline-portable-pack
- **Description**: win整合包skill
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-21
- **Last Updated**: 2026-04-21

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Offline Portable Pack — 离线整合包制作工具集

> **专为国内用户优化的 Windows 离线整合包制作方案**。预置嵌入式运行时，全面接入国内镜像加速，让你无需翻墙即可快速构建 Python / Node.js 项目的 Windows 便携式部署包。

[![Gitee](https://img.shields.io/badge/Gitee-offline--portable--pack-red)](https://gitee.com/qianchilang/offline-portable-pack)

---

## 🛠️ 一句话安装此技能

### Kimi / OpenHands 等 Skill 类代理

直接告诉 AI：

> **"请根据 https://gitee.com/qianchilang/offline-portable-pack/blob/master/README.md 安装 OfflinePortablePack 技能"**

AI 将自动克隆仓库到 `~/.kimi/skills/offline-portable-pack/` 并加载 `SKILL.md`。

### Claude Code

Claude Code 使用 `CLAUDE.md` 文件作为项目指令，有三种等效用法：

**方式一：对话中直接引用（最快捷）**

> **"请参照 https://gitee.com/qianchilang/offline-portable-pack/raw/master/CLAUDE.md 中的规范，协助我制作 Windows 离线整合包。"**

**方式二：项目级持久化（推荐）**

```bash
# 在项目根目录执行
mkdir -p .claude
curl -L -o .claude/CLAUDE.md https://gitee.com/qianchilang/offline-portable-pack/raw/master/CLAUDE.md
```

然后告诉 Claude：**"我已将项目规范写入 .claude/CLAUDE.md，请按此执行。"**

**方式三：全局持久化（所有项目通用）**

```bash
mkdir -p ~/.claude
curl -L -o ~/.claude/CLAUDE.md https://gitee.com/qianchilang/offline-portable-pack/raw/master/CLAUDE.md
```

然后告诉 Claude：**"我已更新全局 CLAUDE.md，请按离线整合包规范协助我。"**

---

## 📦 项目简介

本项目是一套**通用 Windows 离线整合包制作方法论 + 工具集**，适用于：

- ✅ Python 单体应用（Flask / FastAPI / Django / CLI 工具等）
- ✅ Node.js 前端项目（React / Vue / Next.js 等）
- ✅ Python + Node.js 全栈项目
- ✅ 任何使用 `requirements.txt` + `package.json` 管理的项目

**核心优势**：

| 特性 | 说明 |
|------|------|
| 🚀 **本地优先** | 运行时工具预置在项目目录，无需联网下载 |
| 🇨🇳 **国内加速** | pip/npm/GitHub 全面接入国内镜像，告别超时 |
| 📁 **源码分离** | 运行时与业务代码分离，升级互不影响 |
| 🖥️ **ANSI 编码** | 所有 `.bat` 脚本严格使用 GBK 编码，中文 Windows 完美兼容 |
| 💾 **数据持久化** | 用户数据自动存放 `workspace/` 目录，升级不丢失 |

---

## 📂 项目目录

```
offline-portable-pack/
├── SKILL.md                          # 📖 完整制作指南（必读）
├── README.md                         # 📖 本文件
├── CLAUDE.md                         # 🤖 Claude Code 专用指令
├── LICENSE                           # 📄 MIT 许可证
│
├── scripts/                          # 🛠️ 自动化脚本
│   ├── setup.py                      # 安装运行时
│   ├── install_deps.py               # 安装项目依赖
│   ├── test_run.py                   # 测试运行项目
│   ├── package.py                    # 打包发布
│   └── generate_bats.py              # 生成 .bat 入口
│
├── 00_Setup_Runtime.bat              # ⚡ 一键安装运行时
├── 01_Install_Deps.bat               # ⚡ 一键安装依赖
├── 02_Test_Run.bat                   # ⚡ 一键测试运行
├── 03_Build_Package.bat              # ⚡ 一键打包发布
│
├── python-3.11.9-embed-amd64.zip     # 🐍 Python 3.11 嵌入式运行时
├── python-3.12.10-embed-amd64.zip    # 🐍 Python 3.12 嵌入式运行时
├── python-3.13.13-embed-amd64.zip    # 🐍 Python 3.13 嵌入式运行时（最新稳定版）
├── python-3.14.4-embed-amd64.zip     # 🐍 Python 3.14 嵌入式运行时
├── python-3.15.0a8-embed-amd64.zip   # 🐍 Python 3.15 Alpha（预览版）
├── node-v20.12.2-win-x64.zip         # 🟢 Node.js 20 LTS 运行时
└── get-pip.py                        # 📦 pip 安装器
```

> **体积说明**：全部压缩包总计约 **84 MB**，解压后可构建完整离线运行环境。

---

## 🚀 快速开始

### 1. 克隆本项目

```bash
git clone https://gitee.com/qianchilang/offline-portable-pack.git
cd offline-portable-pack
```

### 2. 阅读制作指南

**[📖 SKILL.md](SKILL.md)** 包含完整的制作流程，建议按顺序阅读：

1. 硬约束检查清单（BAT 编码、路径规范等）
2. 国内用户加速指南（镜像源速查表）
3. 制作流程六步法
4. 常见问题排查
5. 实战案例（以 DeepTutor 为例）

### 3. 开始制作你的整合包（两种方式）

#### 方式 A：一键自动化脚本（推荐）

```batch
:: ① 将项目源码放入 app/ 目录（手动克隆或复制）
git clone https://ghfast.top/https://github.com/你的用户名/你的项目.git app

:: ② 双击运行脚本（按顺序执行）
00_Setup_Runtime.bat      # 安装运行时（仅需一次）
01_Install_Deps.bat       # 自动安装 Python + npm 依赖
02_Test_Run.bat           # 测试项目是否能正常启动
03_Build_Package.bat      # 清理、生成启动脚本、打包

:: ③ 在 scripts/ 目录下找到 start.bat，按需修改启动命令
:: ④ 分发生成的 .7z 或 .zip 文件
```

#### 方式 B：手动分步执行

```batch
:: ① 解压运行时
powershell -Command "Expand-Archive -Path 'python-3.11.9-embed-amd64.zip' -DestinationPath 'runtime/python' -Force"

:: ② 克隆项目源码
git clone https://ghfast.top/https://github.com/你的用户名/你的项目.git app

:: ③ 安装依赖
runtime\python\python.exe -m pip install -r app\requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
cd app\frontend && npm install --registry=https://registry.npmmirror.com

:: ④ 手动编写启动脚本并打包
```

> 📌 **详细步骤、脚本模板和避坑指南请查阅 [SKILL.md](SKILL.md)**。

---

## 🌐 国内镜像源速查

本项目已全面接入国内镜像，制作整合包时无需翻墙：

| 类型 | 国内镜像地址 |
|------|-------------|
| **pip** | `https://pypi.tuna.tsinghua.edu.cn/simple` |
| **npm** | `https://registry.npmmirror.com` |
| **GitHub 克隆** | `https://ghfast.top/https://github.com/...` |
| **Python 下载** | `https://mirrors.huaweicloud.com/python/` |
| **Node.js 下载** | `https://registry.npmmirror.com/-/binary/node/` |
| **get-pip.py** | `https://mirrors.tuna.tsinghua.edu.cn/pypa/get-pip.py` |

---

## 🛠️ 包含工具说明

### Python 嵌入式运行时

| 版本 | 文件 | 说明 |
|------|------|------|
| 3.11.9 | `python-3.11.9-embed-amd64.zip` | 最稳定推荐，兼容性最佳 |
| 3.12.10 | `python-3.12.10-embed-amd64.zip` | 稳定版，性能提升 |
| 3.13.13 | `python-3.13.13-embed-amd64.zip` | **最新稳定版** |
| 3.14.4 | `python-3.14.4-embed-amd64.zip` | 前瞻版本 |
| 3.15.0a8 | `python-3.15.0a8-embed-amd64.zip` | 开发预览版 |

> 嵌入式版本体积仅约 **10 MB**（标准安装版约 100+ MB），解压即用，不写注册表。

### Node.js 运行时

| 版本 | 文件 | 说明 |
|------|------|------|
| 20.12.2 LTS | `node-v20.12.2-win-x64.zip` | 长期支持版，推荐用于生产环境 |

### pip 安装器

| 文件 | 说明 |
|------|------|
| `get-pip.py` | 官方 pip 安装脚本，用于为嵌入式 Python 安装 pip |

---

## 📋 使用场景示例

### 场景一：打包 Python CLI 工具

```batch
:: 仅需 Python 运行时，无需 Node.js
:: 解压 python-3.11.9-embed-amd64.zip 到 runtime/python
:: 安装依赖到 runtime/python/Lib/site-packages
:: 编写一个 start.bat 启动你的入口脚本
:: 打包 -> 发给用户，双击即用
```

### 场景二：打包 Next.js 全栈项目

```batch
:: 同时需要 Python + Node.js 运行时
:: 解压两个运行时到 runtime/python 和 runtime/nodejs
:: 安装后端 Python 依赖 + 前端 npm 依赖
:: 编写 start.bat 同时启动后端 API 和前端 Dev Server
:: 打包 -> 用户一键启动前后端
```

### 场景三：制作免安装绿色软件

```batch
:: 将所有依赖预装好
:: 用户数据强制存放 workspace/ 目录
:: 最终用户无需安装 Python/Node.js，无需配置环境变量
:: 即拷即用，升级只需替换 app/ 目录
```

---

## ⚠️ 重要注意事项

### 1. BAT 脚本编码红线

所有 `.bat` 文件**必须使用 ANSI (GBK) 编码**，严禁使用 UTF-8（无论是否带 BOM）。

```python
# 正确写入方式
with open("start.bat", "w", encoding="gbk") as f:
    f.write(content)
```

### 2. 路径必须使用相对路径

```batch
:: ✅ 正确
set "ROOT=%~dp0"
set "PYTHON=%ROOT%runtime\python\python.exe"

:: ❌ 错误
set "PYTHON=C:\Users\Admin\runtime\python\python.exe"
```

### 3. 用户数据隔离

永远将用户数据放在 `workspace/` 目录，避免升级时丢失：

```batch
set "USER_DATA=%ROOT%\workspace\data"
```

---

## 📚 文档索引

| 文档 | 内容 |
|------|------|
| [SKILL.md](SKILL.md) | 完整制作指南、脚本模板、常见问题、实战案例 |
| [README.md](README.md) | 项目简介、快速开始、工具说明（本文） |

---

## 🤝 贡献与反馈

如有问题或建议，欢迎提交 Issue 或 PR。

**镜像源失效？** 国内镜像可能随时变动，如遇到某个镜像无法访问，请：
1. 尝试 SKILL.md 中列出的备用镜像
2. 或提交 Issue 更新镜像地址

---

## 📄 许可证

本项目采用 MIT 许可证。其中包含的 Python、Node.js 等运行时遵循各自官方许可证。

---

> **制作整合包遇到问题？请先仔细阅读 [SKILL.md](SKILL.md) 的"常见问题"章节，90% 的问题都能找到答案。**