Skip to main content

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

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


一、项目简介与核心功能

1.1 这是什么?

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

生成的文件 双击后的效果
install.bat 自动创建一个干净的 Python 虚拟环境,并把你的模块装进去;装完还能自动启动网站
start.bat 自动激活虚拟环境,启动你的网站/服务,并自动打开浏览器

1.2 它解决了什么烦恼?

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

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

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

1.3 适合谁用?

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

二、环境依赖与系统要求

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

项目 要求 怎么检查
操作系统 Windows 10 / 11(生成的是 .bat 脚本,只在 Windows 上双击运行) 看桌面右下角"开始"菜单图标
Python 3.10 或更高版本 命令行输入 python --version
网络 安装工具时需要联网 打开浏览器能上网即可
命令行 系统自带的"命令提示符"或"PowerShell" 按 Win + R,输入 cmd 回车

名词解释(给完全零基础的同学):

  • 命令行 / 命令行窗口:就是一个黑色(或白底)的文字窗口,你在里面输入命令、按回车,电脑就执行。打开方法:按键盘 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
📦 没有发布到 PyPI 时,从源码安装(点我展开)

如果 pip install scriptforge 提示找不到这个包(说明还没发布到 PyPI),你可以直接从源码安装:

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 全部参数一览表

参数 默认值 作用 举例
--module-dir 必填 模块文件夹名(里面要有 pyproject.toml) --module-dir cold_msg
--host 127.0.0.1 网站监听地址 --host 0.0.0.0
--port 6060 网站端口号 --port 7000
--web-cmd 自动推导 启动网站的完整命令 --web-cmd "cold-msg web --reload"
--venv-dir venv 虚拟环境文件夹名 --venv-dir .venv
--start-web / --no-start-web 开启 install 装完后是否自动启动网站 --no-start-web
--open-browser / --no-open-browser 开启 start 启动时是否自动打开浏览器 --no-open-browser
--output-dir 当前目录 脚本生成到哪个文件夹 --output-dir D:\proj
--only 两个都生成 只生成其中一个 --only start

小提示:--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 立刻生成,双击即用。祝使用愉快!🎉

Metadata

Release files for scriptforge 0.1.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for scriptforge 0.1.1
File Size Uploaded Provenance Actions
scriptforge-0.1.1.tar.gz 11.0 kB Without provenance Details for scriptforge-0.1.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for scriptforge 0.1.1
File Interpreter ABI Platform Actions
scriptforge-0.1.1-py3-none-any.whl Python 3 none any Details for scriptforge-0.1.1-py3-none-any.whl

Total release size: 22.2 kB

Release files / scriptforge-0.1.1.tar.gz

Download URL scriptforge-0.1.1.tar.gz
Size 11.0 kB
Tags Source
SHA-256 checksum
How to use checksums
b63ed0ffd50e75668e75c572f3f460ddae12c42a97ecc7f05578919ccb557942
BLAKE2b-256 checksum
How to use checksums
1a1d75ac56d7898b53c945459f3716db1085273290c4562a173fb23044b40b4a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.7

Release files / scriptforge-0.1.1-py3-none-any.whl

Download URL scriptforge-0.1.1-py3-none-any.whl
Size 11.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
112ebe6600f2afcd0529edc05a806955f95db5e3636a86962b6fc06d5b9f37d9
BLAKE2b-256 checksum
How to use checksums
55e6fc195ee8a4ff9d46da59ecbc3b7807efbb721addc87c6a583e0a75390448
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.11.7

Security for scriptforge 0.1.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.1 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page