TeXlive安装后无法识别新宏包？

Question

TeX Live 安装后无法识别新宏包是常见问题，通常源于未正确更新文件名数据库或宏包路径未被纳入搜索范围。用户通过 `tlmgr` 安装新宏包后，若未运行 `mktexlsr` 或 `texhash` 命令刷新文件列表，TeX 引擎将无法定位新宏包。此外，使用用户目录（如 `~/texmf`）时，若目录结构不符合 TDS 规范（如未置于 `tex/latex/` 子目录下），也会导致加载失败。有时编辑器缓存未清除，误报“宏包不存在”。建议安装后执行 `mktexlsr`，确认宏包路径正确，并在 LaTeX 中使用 `\listfiles` 检查是否成功加载。

Answer 1

1. 问题背景与常见现象

在使用 TeX Live 发行版进行 LaTeX 文档编译时，许多用户会遇到“宏包未找到”（Package not found）的错误提示，即使已通过 tlmgr install <package> 成功安装了所需宏包。这一现象在 IT 及科研领域尤为普遍，尤其是在自动化构建流程或跨平台迁移环境中。根本原因往往并非宏包未安装，而是 TeX 系统未能正确识别其存在。

• 错误信息如：! LaTeX Error: File `xxx.sty' not found.
• 使用 tlmgr 安装后仍无法加载新宏包
• 编辑器（如 TeXstudio、VS Code + LaTeX Workshop）缓存误导报错

这类问题对具备 5 年以上经验的开发者而言，虽非致命，但频繁打断工作流，影响研发效率和文档交付进度。

2. 核心机制解析：TeX 的文件搜索路径与数据库

TeX 引擎并不实时扫描整个文件系统来查找宏包，而是依赖一个预生成的“文件名数据库”（Filename Database），该数据库记录了所有可访问的 .sty、.cls、.def 等资源文件的路径。这个数据库由 mktexlsr 或别名 texhash 命令生成。

命令	作用说明
mktexlsr	重建 TeX 文件名数据库，使新安装的宏包被系统识别
texhash	部分系统中为 mktexlsr 的符号链接或别名
kpsewhich -var-value=TEXMFDBS	查看当前参与索引的目录列表

若跳过此步骤，即便物理文件已存在于磁盘，TeX 引擎也无法定位它们。

3. 用户级宏包管理：TDS 规范与路径结构

当用户选择将宏包手动放置于个人目录（如 ~/texmf）而非系统路径时，必须遵循 TeX Directory Structure (TDS) 规范。否则，即使执行 mktexlsr，文件也不会被正确索引。

1. 正确路径示例：~/texmf/tex/latex/<package>/xxx.sty
2. 错误路径示例：~/texmf/xxx.sty（根目录下直接存放）
3. TDS 要求按类型分类：tex/, bibtex/, doc/ 等子目录

可通过以下命令验证路径是否纳入搜索范围：

kpsewhich --all texmf.cnf
kpsewhich -expand-var='$TEXMFHOME'

4. 编辑器与构建系统的缓存干扰

现代 LaTeX 编辑器（如 Overleaf 桌面客户端、TeXworks、Sublime Text 插件）常内置语法检查器和自动补全功能，这些组件可能缓存旧的宏包列表，导致误报“宏包不存在”，即使底层 TeX 系统已正常识别。

graph TD
    A[用户安装宏包 via tlmgr] --> B{是否运行 mktexlsr?}
    B -- 否 --> C[TeX引擎无法定位]
    B -- 是 --> D[更新文件数据库]
    D --> E{编辑器是否清缓存?}
    E -- 否 --> F[显示错误警告]
    E -- 是 --> G[正常识别并加载]

建议操作顺序：

• 安装后立即运行：sudo mktexlsr 或 texhash ~/texmf
• 重启编辑器或触发“刷新项目资源”动作
• 使用 \listfiles 在文档导言区输出加载的宏包版本列表

5. 验证与调试流程：从日志到工具链协同

在复杂 CI/CD 环境中（如 GitLab Pages 构建 PDF 报告），此类问题更难排查。推荐标准化调试流程：

% 在 LaTeX 源码开头添加
\listfiles
\documentclass{article}
\usepackage{newpackage} % 替换为实际宏包名

% 编译后查看 log 文件末尾的文件列表
% 输出格式示例：
*File List*
 article.cls    2024/02/08 v1.4n Standard LaTeX class
 newpackage.sty 2023/05/10 v1.0a New Package
*

结合 shell 层面验证：

# 查询特定宏包路径
kpsewhich newpackage.sty

# 查看当前生效的 texmf 配置
kpsewhich -all texmf.cnf

# 手动刷新用户目录索引
texhash ~/texmf