diff --git a/.gitignore b/.gitignore
index 13a753a..7cff75e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,7 +7,10 @@ node_modules/
 # Build output
 dist/
 public/images/
-ref/
+ref/    
+
+# Environment variables
+.env
 
 # Miscellaneous
 .DS_Store
diff --git a/AGENTS.md b/AGENTS.md
index 8f35039..221279a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -67,7 +67,7 @@
 - Astro 的高保真类型来自 `.astro/types.d.ts`，由 `astro dev` 或 `astro sync` 生成。
 - Node 要求：`>= 18.20.8`（建议 `>= 20`）。Node 版本不足会导致 `astro sync` 失败，类型退化为 `any`（如 `getCollection(...args: any[]): any`）。
 - 操作规范：
-  - 在“非沙盒/本机环境”执行：`astro sync` 或 `pnpm dev`，以生成 `.astro/types.d.ts`。
+  - 在“非沙盒/本机环境”执行：`pnpm astro sync` 或 `pnpm dev`，以生成 `.astro/types.d.ts`。
   - 如在沙盒内执行需要更高权限，请先申请再运行，或直接在沙盒外执行。
   - 若类型仍不生效：删除 `.astro/` 后重跑 `pnpm sync`；确保编辑器使用工作区 TypeScript 版本。
 
diff --git a/README.md b/README.md
index c78f7bd..5c2e258 100644
--- a/README.md
+++ b/README.md
@@ -20,10 +20,11 @@
 - 通用组件：`src/components/`（如 `Img.astro` 支持外部图床）
 - 内容扩展抽象：`src/lib/content/`（为未来 Typst 等格式预留）
 
-## 配置
+## 配置与类型
 
 - `PUBLIC_MEDIA_BASE_URL`：外部图床前缀（避免图片入库）
 - `PUBLIC_SITE_URL`：站点地址（可选，用于 canonical 等）
+- 修改内容集合（src/content/config.ts）后，需在本机运行 `pnpm astro sync`（Node >= 18.20.8，建议 >= 20），以生成 `.astro/types.d.ts`，否则类型可能退化为 any。
 
 ## 约定
 
diff --git a/env.d.ts b/src/env.d.ts
similarity index 81%
rename from env.d.ts
rename to src/env.d.ts
index fce4ffc..bb2efbc 100644
--- a/env.d.ts
+++ b/src/env.d.ts
@@ -1,4 +1,5 @@
 /// <reference types="astro/client" />
+/// <reference path="../.astro/types.d.ts" />
 
 interface ImportMetaEnv {
   readonly PUBLIC_MEDIA_BASE_URL?: string;
@@ -8,4 +9,3 @@ interface ImportMetaEnv {
 interface ImportMeta {
   readonly env: ImportMetaEnv;
 }
-
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 5232ab5..6117fcc 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -17,7 +17,7 @@
   },
   "include": [
     "src",
-    "env.d.ts",
+    "src/env.d.ts",
     "astro.config.mjs",
     ".astro/types.d.ts"
   ],