企业官网建设流程全解析

awesome-python 如何初始化本地开发环境并首次构建静态站点

【免费下载链接】awesome-pythonThe definitive list that answers "I want to do X in Python, which tool should I use?"项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python

awesome-python 仓库的站点内容是单文件驱动：README.md 是唯一的条目来源，website/目录下的构建脚本把它渲染成静态站点。本文的任务是：在本地把仓库跑起来，完成依赖安装和第一次构建，得到一个可浏览的website/output/站点产物。前提条件只有两个：Python 3.14 及以上（pyproject.toml 中requires-python = ">=3.14"），以及 uv 包管理器。

获取仓库并初始化依赖

git clone https://gitcode.com/GitHub_Trending/aw/awesome-python cd awesome-python make install

make install实际执行的是 Makefile 中的uv sync --locked：按仓库内已提交的uv.lock锁定版本安装依赖，创建虚拟环境。这里不需要额外装包——pyproject.toml 定义了 build、lint、test、preview 四个依赖组（jinja2、httpx、markdown-it-py、ruff、ty、pytest、watchfiles），uv sync会一并装好。该文件还配置了no-build = true和only-binary = [":all:"]，即所有依赖只取预构建 wheel，不做源码编译，所以不需要系统级的 C 工具链。

执行首次构建

make build

该目标执行uv run python website/build.py，入口逻辑在 website/build.py 的build()函数。构建过程做了四件事：

1. 解析根目录 README.md 中的分组（如AI & ML、Web Development）与分类（如 Deep Learning），提取每个条目的名称、链接和描述；
2. 读取可选的数据文件website/data/github_stars.json与website/data/pypi_downloads.tsv——这两个文件不是必需的，缺失时构建照常完成，只是条目不显示 star 数和下载量；
3. 用 Jinja2 渲染 website/templates/ 下的模板，生成首页、每个分类/分组/子分类的categories/<slug>/index.html、赞助页、robots.txt、sitemap.xml和llms.txt；
4. 把 website/static/ 整目录复制到输出目录。

注意一个副作用：构建脚本在开始前会先删除已存在的website/output/目录再全量重建，所以重复执行make build是幂等的，旧的分类页面不会残留。

构建成功时脚本在终端打印三行汇总（分组数、分类数、总条目数和输出目录路径）。成功判定以产物为准：

ls website/output

应看到index.html、categories/、sponsorship/、robots.txt、sitemap.xml、llms.txt、static/。

用测试套件核对产物

项目自带针对构建输出的测试 website/tests/test_build.py，覆盖首页元数据、分类页 JSON-LD、sitemap、llms.txt 等内容。运行：

make test

实际执行uv run pytest website/tests/ -v（测试路径由 pyproject.toml 的testpaths = ["website/tests"]指定）。全部通过即说明首次构建产出的页面结构与预期一致，这是不打开浏览器时最直接的验证方式。

可选：拉取 star 数与 PyPI 下载量数据

首次构建不带数据也能成功。如果想让页面显示 star 数和月下载量，在构建前执行抓取脚本，再重新make build：

export GITHUB_TOKEN=<你的 GitHub token> make fetch_github_stars

• 副作用：脚本通过 GitHub GraphQL API 批量抓取 README.md 中所有仓库的 star 数（每批 50 个），结果写入website/data/github_stars.json，12 小时内的缓存不会重复拉取。
• 前提：GITHUB_TOKEN环境变量是必需的，未设置时脚本直接报错退出：Error: GITHUB_TOKEN environment variable is required.。Makefile 开头有-include .env和export，所以也可以把GITHUB_TOKEN写进.env文件，不必每次 export。
• 限制：website/fetch_github_stars.py 的说明里明确website/data/下的数据文件被 gitignore，CI 在部署时才拉取，本地抓取仅用于预览，不要提交这些数据。

PyPI 下载量不需要任何密钥（走 ClickPy 的公开镜像端点）：

make fetch_pypi_downloads

该脚本是website/data/pypi_downloads.tsv的唯一写入者，每次运行从零重写整个文件，README.md 中已删除的条目会自然消失。注意其文档字符串中的口径说明：这份计数包含镜像/CI 流量，不能与 pypistats.org 的数字混用。

本地预览：热重载 + 本地服务器

修改 README 或模板后想看实时效果，用：

make preview

这个目标先执行build，然后并行做两件事（见 Makefile 的preview目标）：

• watchfiles监听README.md、website/templates、website/static、website/data的变化，任一变化就自动重跑python website/build.py；
• python -m http.server -b 127.0.0.1 -d website/output/ 8000把构建产物作为静态站点服务在http://127.0.0.1:8000。

浏览器访问http://127.0.0.1:8000即可看到首页；Ctrl+C停止。它只绑定 127.0.0.1，是本机预览用途。

构建失败时的两个已知情况

• slug 冲突：当某个分类名与某个分组名（或内置的built-in）生成的 slug 相同时，构建会抛出ValueError: slug collision in /categories/ namespace: [...]，错误信息同时给出处理建议（重命名分类或分组使 slug 不同）。这是 website/build.py 中唯一的显式前置校验。
• 数据文件过期或缺失：数据文件缺失只影响展示（无 star/下载列），不会报错；若抓取到一半网络中断，GitHub star 脚本按批次保存，已有部分缓存保留。

后续可用的检查命令

首次构建跑通后，Makefile 还提供了与开发相关的入口：make lint（uv run ruff check .）、make typecheck（uv run ty check website）。若要修改站点模板或解析逻辑，对应的行为基线在 website/tests/ 中，改完代码后以make test复核即可。

【免费下载链接】awesome-pythonThe definitive list that answers "I want to do X in Python, which tool should I use?"项目地址: https://gitcode.com/GitHub_Trending/aw/awesome-python