用Python生成一个静态的index.html文件，看似简单，但选错方法后续维护会困难重重。本文介绍几种主流做法，从最直接的方式到适合批量生产的方案，帮助你避开常见问题。

使用 open() 和字符串拼接最稳妥

生成HTML文件本质上是将文本写入文件。最可靠、最无“魔法”的方式，就是直接使用Python内置的open()函数配合字符串。对于小项目，不必急于寻找模板引擎，那只会增加依赖和复杂度。

但新手容易犯两个错误：一是忘记指定encoding='utf-8'，导致中文乱码或写入失败；二是未意识到'w'模式会直接清空目标文件（即使文件原本不存在）。

写之前需要确认以下几点：

• 路径可写：如果在当前目录生成，直接使用'index.html'；若要放入./dist/等子目录，需先通过os.makedirs('./dist', exist_ok=True)创建目录。
• HTML结构完整：务必包含</code>和，前者声明HTML5，后者确保中文正常显示。
• 用户输入需转义：若页面标题、内容来自用户输入，必须使用html.escape()进行转义。这不仅能防御XSS攻击，还能避免特殊字符（如<）破坏HTML标签结构。

完整示例代码如下：

from html import escape

title = "我的首页"
content = "
欢迎访问
"

with open('index.html', 'w', encoding='utf-8') as f:
    f.write(f'''






{content}

''')

借助 string.Template 管理多段 HTML 更清晰
当页面结构固定，但某些区域（如导航栏、页脚）需要复用时，继续用f-string硬拼接会使代码难以维护。此时，标准库中的string.Template是一个轻量又优雅的选择。它比jinja2等全功能模板引擎更简单，无需学习新概念，同时又比纯字符串拼接更清晰。
注意，string.Template仅支持简单的占位符替换，无法实现条件判断或循环。另外，变量名必须是合法的Python标识符，调用.substitute()时模板中所有占位符都必须提供对应值，否则会抛出KeyError。
使用技巧：

不必为使用模板而将HTML拆成多个文件。可以通过Path.read_text()从文件中读取模板字符串。
占位符可写成$title或${title}，后者在变量名后紧跟字母或数字时更安全，避免歧义。
如果某个变量可能为空（如可选的副标题），建议在传入前用or ''赋予空字符串默认值，避免传入None。

from string import Template

template_str = '''





  
$heading
  $content

'''

t = Template(template_str)
html = t.substitute(
    title="首页",
    heading="欢迎光临",
    content="
这是主页内容
"
)

with open('index.html', 'w', encoding='utf-8') as f:
    f.write(html)

用 pathlib.Path.write_text() 替代 open() 更简洁
若你使用的是Python 3.4或更高版本，强烈推荐用pathlib模块处理所有路径操作。Path.write_text()方法非常适合生成单个文件这类简单任务，它自动处理文件编码和关闭，使代码异常简洁，减少因忘记关闭文件或指定编码而出错的概率。
需要注意：write_text()默认使用utf-8编码，若显式传入encoding参数，必须与写入内容编码一致。此外，它只支持覆盖写入模式，不支持追加。
用好pathlib能让代码更“Pythonic”：

路径对象支持链式操作，例如Path('dist').joinpath('index.html').write_text(...)，非常直观。
写入前，可用parent.mkdir(parents=True, exist_ok=True)确保目标文件的父目录存在。
注意不要对同一个Path对象反复调用write_text()，因为每次都会全量重写，而非增量追加。

from pathlib import Path

html_content = '
Hello
'
output_path = Path('dist/index.html')
output_path.parent.mkdir(parents=True, exist_ok=True)
output_path.write_text(html_content, encoding='utf-8')

生成静态站点时，避免手写完整 HTML 结构
前面介绍了生成单个页面的方法。当需要批量生成多个页面（例如将一堆Markdown文章转换为静态博客）时，若在每个脚本中硬编码完整的...结构，维护将极其困难。
此时核心思路是分离“内容”和“外壳”。只需关注每篇文章的正文内容（比如用markdown库转换Markdown），然后借助通用模板（如string.Template）将正文“套”进去。这样，若要修改网站全局的页脚，只需改动一个模板文件即可。
真正的难点在于如何优雅管理多页面共享的部件：

使用markdown库转换正文，再用string.Template套上外壳，两步分离，逻辑清晰。
不要在生成脚本中硬编码CSS或JS的绝对路径，使用相对路径（如./style.css），并确保最终输出的目录结构一致。
若网站最终部署到子路径下（如https://example.com/blog/），所有内部链接（包括CSS、JS、站内文章链接）都需要带上该前缀。此时，用一个配置项控制前缀，远比生成后全局搜索替换更可靠。

前期多花十分钟设计清晰的结构，后期可节省几十小时的补救时间。这一道理同样适用于生成静态HTML文件。