scriptforge — 一键生成 Python 项目的安装与启动脚本

一个简单好用的命令行小工具，帮你瞬间生成 install.bat（安装脚本）和 start.bat（启动脚本），从此新建项目再也不用手写、复制、改配置。

一、项目简介与核心功能

1.1 这是什么？

scriptforge 是一个命令行工具（就是在黑色命令行窗口里敲命令用的程序）。你敲一行命令，它就能在当前文件夹里生成两个文件：

1.2 它解决了什么烦恼？

没有这个工具时，每新建一个 Python 项目，你都得：

1. 找以前项目的 install.bat、start.bat 复制过来；
2. 打开文件，找到顶部的 CONFIG（配置）段；
3. 手动改 MODULE_DIR（模块名）、WEB_PORT（端口）、WEB_CMD（启动命令）……
4. 改错一个字母，脚本就跑不起来。

有了 scriptforge，一条命令搞定，参数填对就行，不用再碰脚本内部。

1.3 适合谁用？

• 经常新建 Python 项目、想快速配上"双击即装 / 双击即启"脚本的同学；
• 想把项目分享给别人，让对方"双击就能跑起来"的同学；
• 不想每次都手写 .bat 脚本的同学。

二、环境依赖与系统要求

在开始之前，请确认你的电脑满足以下条件：

名词解释（给完全零基础的同学）：

• 命令行 / 命令行窗口：就是一个黑色（或白底）的文字窗口，你在里面输入命令、按回车，电脑就执行。打开方法：按键盘 Win + R，在弹出的小框里输入 cmd，按回车。
• 虚拟环境（venv）：可以理解成一个"专属小房间"，里面装的 Python 包不会影响电脑上其他项目，互不干扰。

三、详细的安装与配置步骤

第 1 步：确认 Python 已正确安装

打开命令行窗口（Win + R → 输入 cmd → 回车），输入：

python --version

如果看到类似下面的输出，说明 Python 已装好：

Python 3.11.7

如果提示"不是内部或外部命令"，说明还没装 Python。请去 python.org 下载安装，安装时务必勾选 "Add Python to PATH"（把 Python 加入环境变量），这一步很重要！

第 2 步：安装 scriptforge

在命令行里输入下面这条命令并回车：

pip install scriptforge

稍等几秒，看到 Successfully installed ... 就表示装好了。

如果你的网络较慢、一直卡住，可以加一个国内镜像加速：

pip install scriptforge -i https://pypi.tuna.tsinghua.edu.cn/simple

cd scriptforge
pip install .

cd scriptforge
pip install -e .

第 3 步：验证安装成功

输入：

scriptforge --help

看到一段帮助说明（列出所有可用参数），就说明安装成功、可以用了。

 Usage: scriptforge [OPTIONS]

 Options:
 --module-dir TEXT          模块目录名（含 pyproject.toml）  [required]
 --host TEXT                Web 监听地址  [default: 127.0.0.1]
 --port INTEGER             Web 端口  [default: 6060]
 --web-cmd TEXT             启动命令，留空则自动推导
 --venv-dir TEXT            虚拟环境目录名  [default: venv]
 --start-web/--no-start-web install 完成后是否启动 Web  [default: start-web]
 --open-browser/--no-open-browser  start 是否自动打开浏览器  [default: open-browser]
 --output-dir PATH          脚本输出目录  [default: .]
 --only TEXT                只生成某一个: install | start
 --help                     Show this message and exit.

四、基础使用方法与示例

4.0 先了解：你的项目应该长什么样

scriptforge 生成的脚本默认假设你的项目目录是这样的：

我的项目/                  ← 项目根目录（脚本生成在这里）
|-- cold_msg/              ← 模块文件夹（里面要有 pyproject.toml）
|   |-- pyproject.toml
|   |-- cold_msg/
|   `-- ...
|-- install.bat            ← scriptforge 生成
`-- start.bat              ← scriptforge 生成

关键点：模块文件夹里必须有一个 pyproject.toml 文件（这是 Python 项目的"说明书"）。

4.1 示例 1：最简单的用法（生成两个脚本）

打开命令行，用 cd 命令进入你的项目根目录，然后执行：

scriptforge --module-dir cold_msg

• --module-dir cold_msg：告诉它你的模块文件夹叫 cold_msg。

运行后你会看到类似下面的输出：

generated: install.bat
generated: start.bat

这时当前目录下就多了 install.bat 和 start.bat 两个文件。默认配置是：地址 127.0.0.1、端口 6060、自动打开浏览器、安装完自动启动。

4.2 示例 2：换个端口

想让网站跑在 7000 端口？加个 --port：

scriptforge --module-dir cold_msg --port 7000

生成的脚本里 WEB_PORT 就会变成 7000。

4.3 示例 3：自己指定启动命令

如果你的启动命令不是默认的 模块名 web --host ... --port ...，可以用 --web-cmd 完全自定义：

scriptforge --module-dir cold_msg --web-cmd "cold-msg web --reload"

注意：命令里有空格，所以要用双引号 " 把整条命令包起来。

4.4 示例 4：安装完不要自动启动

有时候你只想先装好，等会儿再手动启动。加 --no-start-web：

scriptforge --module-dir cold_msg --no-start-web

这样 install.bat 装完就结束，不会自动启动网站。

4.5 示例 5：只生成一个脚本

只想生成 start.bat，不要 install.bat：

scriptforge --module-dir cold_msg --only start

同理，--only install 只生成安装脚本。

4.6 示例 6：生成到别的文件夹

想把脚本生成到别处（比如桌面某个文件夹）：

scriptforge --module-dir cold_msg --output-dir D:\我的项目

4.7 生成之后怎么用？

双击 install.bat（第一次使用时）：

1. 它会检查 Python 是否可用；
2. 创建一个名叫 venv 的虚拟环境（已存在则跳过）；
3. 升级 pip，然后 pip install . 把你的模块装进去；
4. 默认装完自动启动网站并打开浏览器。

下面的代码块模拟你在命令行双击 install.bat 后看到的效果：

============================================================
  Python Module Install Script
  project root : D:\我的项目
  module dir   : D:\我的项目\cold_msg
  venv dir     : D:\我的项目\venv
  start web    : 1
============================================================

[1/4] check python version ...
Python 3.11.7
[2/4] create venv at D:\我的项目\venv ...
[3/4] upgrade pip ...
[3/4] install module: pip install "D:\我的项目\cold_msg"
[4/4] start web server and open browser ...

双击 start.bat（已经装过、以后每次启动时）：

1. 激活虚拟环境；
2. 启动你的网站/服务；
3. 默认自动打开浏览器访问 http://127.0.0.1:6060。

想停止网站：在运行它的命令行窗口里按 Ctrl + C。

4.8 全部参数一览表

小提示：--start-web 和 --open-browser 这类开关，写它就是"开"，加个 no- 前缀就是"关"。例如 --open-browser（开浏览器）vs --no-open-browser（不开浏览器）。

五、常见问题解答（FAQ）与故障排除

安装类

Q1：运行 pip install scriptforge 报错 "找不到这个包"？ 说明它还没发布到 PyPI。请改用源码安装（见"第三步"里展开的"从源码安装"小节）。

Q2：pip install 一直卡住不动？ 多半是网络慢。换国内镜像：

pip install scriptforge -i https://pypi.tuna.tsinghua.edu.cn/simple

Q3：提示 "pip 不是内部或外部命令"？ 说明 Python 没加入环境变量。重新运行 Python 安装包，勾选 "Add Python to PATH"，或手动把 Python 的 Scripts 目录加到系统环境变量 PATH 里。

Q4：提示 "python 不是内部或外部命令"？ 同 Q3，Python 没装或没加入 PATH。去 python.org 下载安装，勾选 "Add Python to PATH"。

使用类

Q5：运行 scriptforge --help 提示"不是内部或外部命令"？ 工具没装好，或没装到当前 Python 里。重新执行 pip install scriptforge，确认看到 Successfully installed。

Q6：忘了写 --module-dir，报错退出？ 这个参数是必填的，不写就会报错。请务必带上，例如 scriptforge --module-dir cold_msg。

Q7：--only 后面乱填了一个值，报错？ --only 只接受 install 或 start 两个值，其他都会报错退出。例如 --only start。

Q8：生成的脚本里 WEB_CMD 是怎么来的？ 如果你没写 --web-cmd，它会自动拼成：模块名 web --host 地址 --port 端口。例如模块叫 cold_msg、端口 6060，就是 cold_msg web --host 127.0.0.1 --port 6060。想完全自定义就用 --web-cmd。

生成的脚本运行类

Q9：双击 install.bat 提示 "pyproject.toml not found"？ 说明 --module-dir 指的文件夹里没有 pyproject.toml。请检查：① 文件夹名是否拼对；② 该文件夹里确实有 pyproject.toml 这个文件。

Q10：双击 install.bat 提示 "python not found in PATH"？ 电脑上没装 Python，或没加入环境变量。先装 Python 3.10+ 并勾选 "Add Python to PATH"，再重新双击。

Q11：双击 start.bat 提示 "venv not found"？ 说明还没运行过 install.bat（虚拟环境还没创建）。请先双击 install.bat 完成安装，再双击 start.bat。

Q12：启动网站时报错"端口被占用"？ 说明 6060（或你设的端口）已经有别的程序在用。换一个端口重新生成脚本即可：

scriptforge --module-dir cold_msg --port 8080

Q13：浏览器没自动打开？ 检查生成时是否用了 --no-open-browser。如果没加却没打开，可能是系统默认浏览器设置异常，手动在浏览器地址栏输入 http://127.0.0.1:6060（端口换成你设的）即可。

Q14：想停止正在运行的网站？ 在运行 install.bat 或 start.bat 的那个命令行窗口里，按 Ctrl + C 即可停止。

Q15：改了参数想重新生成，会覆盖旧脚本吗？ 会。scriptforge 默认覆盖已存在的 install.bat / start.bat，并打印 generated: ... 提示。原来的脚本会被替换成新内容。

六、一句话总结

scriptforge --module-dir 你的模块名

就这一条，install.bat 和 start.bat 立刻生成，双击即用。祝使用愉快！🎉