呗老心眼极小那行提示如果出现在你屏幕上，第一反应不应该是急着关掉，而是把它当作一次安全警示的入口——尤其是你处理的是 Typst 这种“源代码即文档”的排版系统时。程序员圈子里对 Typst 的普遍印象是“比 LaTeX 好上手、比 Word 靠谱”，但很少有人把 .typ 当作一种有格式、有边界、有权限语义的源文件来学习。这恰好意味着，多数人在第一次接触 Typst 项目时，会把源文件当成普通文本去读，忽略了它内部也存在模块引用、本地资源读取、包解析这些需要安全边界的行为。
这轮总结里我不打算只列语法关键词，而是从一份 .typ 文件从创建、编写、模块拆分、编译输出到最终预览的完整链路入手，把 Typst 的源文件格式彻底讲清楚。内容同时兼顾三件事：源文件本身的语法分层、项目里多文件协作时的设计思路，以及预览工具弹“不受信任目录”警告时背后到底在拦什么。无论你是刚开始用 Typst 写简历和论文，还是已经在团队里试着拿它做标准化文档流水线，这篇文章应该都能帮你把“文件格式”四个字从表层的后缀名认知，落到真正可执行的工程理解上。
1. “未授信目录”的提示，恰好引出 Typst 源文件格式的核心话题
1.1 从 .typ 后缀开始，区分“格式”与“标记”
先解决一个最容易混淆的概念：Typst 源文件的后缀是 .typ，本质上是一个 UTF-8 编码的纯文本文件。所谓“文件格式”，并不是指二进制层面有某种专有的编码规则，而是指 Typst 编译器会按照一套特定语法去解析这个文本文件，并把解析结果渲染成带有页面模型的内容。
当你的浏览器或在线文件预览器弹出“预览源文件来自未授信的目录，请停止访问!”，说明预览端已经不把 .typ 当纯文本，而是把它当作“可执行的源文件”在对待。这类拦截在很多文档工具链里都有，比如某些在线 Office 组件遇到从缓存目录、临时上传目录或浏览器隔离目录里加载的文档时，会直接拒绝预览。和 Typst 放一起理解就特别合适：.typ 文件虽然打开后是一行一行的文字，但它内部可能有 #import、#include、#image()、#embed 这类指令，会让编译器去读取同一目录、上级目录甚至网络位置上的其他文件。如果某个工具只把源文件丢进沙箱，却没有把整个项目目录一并挂载进去，那么预览行为就等同于“在未完全信任的环境里执行代码”。
很多人在这一步会直接联想到病毒或恶意脚本。其实更准确的说法是：预览工具无法判断这个目录里的 .typ 文件是否经过项目所有者确认，所以它选择保守策略，也就是不加载不被信任的路径。如果你自己编写 Typst 文件，使用 typst compile 在本地终端中编译，通常不会遇到这种阻断，因为终端进程被赋予的权限来自用户显式发起的命令。
1.2 Typst 源文件为什么需要特别关注权限模型的边界
我可以说一个亲测的场景：做一个包含模板函数的内部工具库时，我习惯把公共样式写在 assets/theme.typ 里，然后在不同子项目的 main.typ 中 #import "../assets/theme.typ": *。这种跨目录引用在命令行下没有任何问题，因为本地文件系统的路径解析由操作系统处理，Typst 进程能直接访问。
但如果是通过部署在服务器上的预览工具加载，事情就完全变了。服务器端能读到的路径仅限于它配置好的目录映射。当用户上传一个 main.typ，它被暂时存放在某个临时文件夹里，此时预览程序如果还想继续解析 ./assets/theme.typ，就必须有能力在那个临时文件夹的上级路径中找到真实项目文件。如果找不到，这个源文件就被判定为“孤立文件”。
那种情况下，工具给出的提示通常就是“预览源文件来自未授信的目录”。换句话说，它警告的不是“Typst 文件有病毒”，而是“当前项目的文件引用链不完整，我们无法保证这个源文件需要的那套目录结构是安全的”。
通过这个视角再去看 Typst 源文件的格式，就应该形成一种习惯：.typ 文件不是一个单一文档，它是一份项目清单。只要涉及多个模块、多个资源文件，就必须把“源文件所在目录”作为基本信任边界来设计。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。